> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a workspace and run your first shell command with the OSS Server API.

First, [start a local server](https://docs.mirage.strukto.ai/home/access/http.md#launch-a-server) and leave it
running. The examples below use `http://127.0.0.1:8765`.

In a second terminal, check that the server is reachable:

```bash theme={null}
curl --fail --silent --show-error http://127.0.0.1:8765/v1/health
```

The response includes `"status": "ok"`. Set the same token you configured on
the server in this terminal before sending authenticated requests:

```bash theme={null}
export MIRAGE_AUTH_TOKEN='replace-with-your-token'
```

The requests below use `--fail-with-body`, available in curl 7.76.0 or newer.
Check with `curl --version`. With an older curl, replace it with `--fail`;
HTTP errors still exit nonzero, but their response bodies are omitted.

Create a workspace with an in-memory mount:

```bash theme={null}
curl --fail-with-body --request POST \
  --url 'http://127.0.0.1:8765/v1/workspaces' \
  --header "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"id":"demo","config":{"mounts":{"/":{"vfs":"ram","mode":"write"}}}}'
```

A successful response has status `201` and includes the workspace ID `demo`. Supply either `config` or a saved
`template`. An identical retry can return `200`; an existing ID with a different
configuration returns `409`.

Run a shell command:

```bash theme={null}
curl --fail-with-body --request POST \
  --url 'http://127.0.0.1:8765/v1/workspaces/demo/shell' \
  --header "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"command":"echo hello"}'
```

The response contains the output and command exit status:

```json theme={null}
{"exit_code":0,"stdout":"hello\n","stderr":"","decision":null,"line_id":"line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37"}
```

Read workspace command logs:

```bash theme={null}
curl --fail-with-body --request GET \
  --url 'http://127.0.0.1:8765/v1/workspaces/demo/logs?limit=50' \
  --header "Authorization: Bearer $MIRAGE_AUTH_TOKEN"
```

Logs return an object with `items` and `next`. Follow `next` using the `after`
query parameter for another page. See [List workspace logs](https://docs.mirage.strukto.ai/api/operations/workspaces/list-workspace-logs.md)
for the fields and a complete response example.

Browse the resource groups on the left or use [endpoint search](https://docs.mirage.strukto.ai/api/reference.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.