> For the complete documentation index, see [llms.txt](https://docs.orchard.airoverflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orchard.airoverflow.com/api/resources/remote.md).

# External sandboxes and credentials

Cloud sandboxes run on a provider (Modal, Daytona, E2B) rather than a node. They are addressed by their **uuid** (the numeric record id is still accepted for back-compat), gated by the `platform.remote` feature, and unlocked by a per-workspace provider credential. They also appear in the unified `GET /instances` list with `location: "remote"`.

## Provider credentials

A credential is workspace-scoped. The secret is write-only: it is verified against the provider, encrypted, and never returned.

| Method | Path                | Does                                                                                                   |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------ |
| GET    | `/credentials`      | Stored credentials for the workspace (no secrets).                                                     |
| POST   | `/credentials`      | Add or update one. Body `{ provider, key, label?, config? }`. The key is verified before it is stored. |
| DELETE | `/credentials/<id>` | Remove one. Org or workspace admin only.                                                               |

```bash
curl -X POST -H "Authorization: Bearer $ORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"modal","key":"<token_id>:<token_secret>"}' \
  https://orchard.example.com/api/credentials
```

Key format is per provider; Modal is `"token_id:token_secret"`.

## Catalog

| Method | Path              | Does                                                                                                             |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET    | `/remote/catalog` | `{ enabled, providers: [{ kind, display, needs_credential, configured }] }`. `configured` means a key is stored. |

## Sync (adopt external sandboxes)

| Method | Path           | Does                                                                                                                                                                      |
| ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/remote/sync` | Adopt provider sandboxes Orchard does not track yet (ones launched directly on Modal/Daytona/E2B), across every credential in the workspace. Returns `{ adopted, live }`. |

Set `config.auto_sync: true` on a credential (in the credential's `config`) to reconcile automatically on every list, so externally launched sandboxes appear without an explicit sync. Adopted sandboxes are given a workspace-unique name.

## Lifecycle

| Method | Path                 | Does                                   |
| ------ | -------------------- | -------------------------------------- |
| POST   | `/remote/create`     | Create a sandbox.                      |
| GET    | `/remote/<id>`       | Detail (the sandbox shape).            |
| DELETE | `/remote/<id>`       | Terminate.                             |
| POST   | `/remote/<id>/start` | Start (providers that support resume). |
| POST   | `/remote/<id>/stop`  | Stop.                                  |

### Create body

| Field         | Default          | Meaning                                            |
| ------------- | ---------------- | -------------------------------------------------- |
| `provider`    | required         | `modal`, `daytona` or `e2b`. A key must be stored. |
| `name`        | required         | Unique within provider + workspace.                |
| `image`       | provider default | Registry tag the provider understands.             |
| `cpu`         | 1                | vCPUs (quota-checked).                             |
| `memory_mb`   | 1024             | Memory (quota-checked).                            |
| `region`      | provider default | Placement.                                         |
| `ttl_minutes` | none             | Auto-terminate after N minutes.                    |
| `extra`       | `{}`             | Provider-specific extras.                          |

```bash
curl -X POST -H "Authorization: Bearer $ORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"modal","name":"build-box","image":"python:3.12-slim","cpu":2,"memory_mb":2048}' \
  https://orchard.example.com/api/remote/create
```

## Files and metrics

| Method | Path                                | Does                                                       |
| ------ | ----------------------------------- | ---------------------------------------------------------- |
| GET    | `/remote/<id>/files?path=`          | List a directory: `{ path, entries: [{ name, is_dir }] }`. |
| POST   | `/remote/<id>/files`                | Upload a file (multipart `file` \[, `path`]).              |
| GET    | `/remote/<id>/files/download?path=` | Download a file (octet-stream).                            |
| GET    | `/remote/<id>/metrics`              | A live cpu/mem/uptime sample taken inside the sandbox.     |

A sandbox reports what it supports with `can_shell`, `can_files`, `can_logs`, `can_metrics` in its shape; an unsupported operation returns `400`.

## Shell and logs

Interactive shell and the log stream are WebSockets:

```
wss://<host>/ws/remote/<id>/shell?token=<api-key-or-jwt>
wss://<host>/ws/remote/<id>/logs?token=<api-key-or-jwt>
```

The shell is raw terminal bytes in both directions (no resize framing). Logs are output-only text frames; a sandbox with no long-running entrypoint is usually quiet, so run a command in the shell to see output. See [WebSocket channels](/api/resources/websockets.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.orchard.airoverflow.com/api/resources/remote.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.