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

# AmikaClient

> Collection-by-collection reference for the TypeScript SDK client.

`AmikaClient` is the entry point for the TypeScript SDK. Construct one with a
credential, then call methods on its collections, such as `client.rigs` and
`client.agentSessions`.

## Constructor

```ts theme={null}
new AmikaClient({
  apiKey?: string,           // provide exactly one of apiKey,
  accessToken?: string,      // accessToken,
  tokenSource?: TokenSource, // or tokenSource
  baseUrl?: string,          // defaults to "https://app.amika.dev"
  fetch?: typeof fetch,      // optional override for tests or polyfills
})
```

* `apiKey`: a static Amika API key. This is the preferred option for scripts.
* `accessToken`: a static bearer token.
* `tokenSource`: an object whose `token()` method the client calls for every
  request. See [Token sources](https://docs.amika.dev/sdks/typescript/token-sources.md).
* `baseUrl`: the API origin. The client appends `/api/v0beta1`.
* `fetch`: a custom `fetch` for tests or non-standard runtimes.

The constructor throws an `AmikaError` unless exactly one of `apiKey`,
`accessToken`, or `tokenSource` is set, and static credentials must be
non-empty. The SDK does not read `AMIKA_API_KEY` from the environment or
disk. You source the credential yourself.

## Collections

All methods return promises, except `handle()`, which makes no request.
HTTP paths below are relative to the `/api/v0beta1` prefix.

| Collection | Methods |
| - | - |
| `client.rigs` | `create`, `list`, `get`, `handle`, `getAndWait` |
| `client.agentSessions` | `send`, `sendStream`, `list`, `get` |
| `client.snapshots` | `create`, `list`, `get`, `handle`, `previewScrub` |
| `client.services` | `list`, `create`, `replace`, `delete` |
| `client.secrets` | `list`, `create`, `update` |
| `client.agentCredentials` | `create`, `list`, `delete` |
| `client.repositories` | `list` |

Ordinary requests time out after 30 seconds. Agent sends time out after 10
minutes. HTTP failures throw `AmikaHTTPError`. See
[Errors](https://docs.amika.dev/sdks/typescript/errors.md).

## Rigs

| Method | Returns | HTTP |
| - | - | - |
| `rigs.create(req: CreateRigRequest)` | `Rig` | `POST /rigs` |
| `rigs.list()` | `Rig[]` | `GET /rigs` |
| `rigs.get(nameOrId)` | `Rig` | `GET /rigs/{ref}` |
| `rigs.handle(nameOrId)` | `RigHandle` | none |
| `rigs.getAndWait(nameOrId, options?)` | `Rig` | polls `GET /rigs/{ref}` |

* `create` returns the rig's initial metadata before setup finishes. Call
  `rig.wait()` to wait for it to be ready.
* `get` rejects if the rig is missing or inaccessible. It returns stopped rigs
  too, without starting them.
* `handle` builds a `RigHandle` from a name or ID without a request or an
  existence check.
* `getAndWait` fetches a rig and waits for it under one deadline.

To run the rig on one of your organization's own hosts, pass the host's ID as
`hostId`. See [Bring your own compute](https://docs.amika.dev/guides/byoc.md).

### `Rig` and `RigHandle`

A `RigHandle` has operations but no fetched data. A `Rig` is the rig's fetched
metadata (`RemoteRig`) plus the same operations, bound to the rig's ID.

| Method | Returns | HTTP |
| - | - | - |
| `fetch()` | `Rig` | `GET /rigs/{ref}` |
| `wait(options?: RigWaitOptions)` | `Rig` | polls `GET /rigs/{ref}` |
| `start()` | `void` | `POST /rigs/{ref}/start` |
| `stop()` | `void` | `POST /rigs/{ref}/stop` |
| `delete()` | `void` | `DELETE /rigs/{ref}` |
| `send(req: AgentSendRequest)` | `AgentSessionSendResponse` | `POST /agent-sessions` |
| `sendStream(req, handlers?)` | `AgentSessionSendResponse` | `POST /agent-sessions/stream` |
| `refresh()` (`Rig` only) | `Rig` | `GET /rigs/{ref}` |

`start()` and `stop()` resolve when the server accepts the request. Call
`wait()` to wait for the new state. Fetched data is a snapshot, not a live
view: `refresh()` and `wait()` update and return the same object.

```ts theme={null}
const handle = client.rigs.handle("dev-box"); // No request.
await handle.start();
const rig = await handle.wait(); // Running, with setup finished.

await rig.stop();
await rig.wait({ status: "stopped" });
```

### Waiting

`wait()` and `getAndWait()` take `RigWaitOptions`:

| Option | Default | Meaning |
| - | - | - |
| `status` | `"running"` | `running`, `stopped`, or `suspended`, or an array where any status matches |
| `setupStatus` | `"ok"` when `running` is a target | Also require the setup script to have succeeded |
| `pollMs` | `3000` | Delay between checks, in milliseconds |
| `maxWaitMs` | `900000` (15 minutes) | Total deadline, including the first fetch |

Waiting for `stopped` also accepts `suspended`. Waiting never creates or
starts a rig. If provisioning fails, setup fails, or the deadline passes,
`wait()` throws an `AmikaWaitError`. HTTP errors, including 404, propagate
immediately without retries.

## Agent sessions

An agent session is a durable chat with a coding agent. Its transcript is
stored on the server and can outlive the rig it ran on.

| Method | Returns | HTTP |
| - | - | - |
| `agentSessions.send(req: AgentSessionSendRequest)` | `AgentSessionSendResponse` | `POST /agent-sessions` |
| `agentSessions.sendStream(req, handlers?)` | `AgentSessionSendResponse` | `POST /agent-sessions/stream` |
| `agentSessions.list(options?)` | `ListAgentSessionsResponse` | `GET /agent-sessions` |
| `agentSessions.get(sessionId)` | `AgentSession` | `GET /agent-sessions/{id}` |

* `send` resolves when the agent turn finishes. Pass `sessionId` to continue a
  chat or `rigId` to target a rig. With neither, the server can create a rig,
  using `repoUrl` if you pass one.
* `sendStream` does the same, calling `onStatus(phase, rigId)` and
  `onDelta(text)` in order as the turn runs. The SDK awaits each callback, and
  a callback that rejects fails the send.
* `list({ limit, rigRef })` returns `{ sessions, total }`, newest first.
  `limit` defaults to 50 on the server. `total` can be larger than
  `sessions.length`.
* `get` returns an `AgentSession`: the chat, its `messages` transcript, and
  bound `send`, `sendStream`, and `refresh` methods.

An agent failure returns `isError: true` with details in `response`, even when
the HTTP request succeeds. If a stream ends without a final result, the SDK
throws. Check the chat before retrying, because the turn may have completed.

```ts theme={null}
const chat = await client.agentSessions.get(turn.sessionId);
await chat.sendStream(
  { message: "Explain the test setup" },
  { onDelta: (text) => process.stdout.write(text) },
);
await chat.refresh(); // Reload the transcript.
```

## Snapshots

| Method | Returns | HTTP |
| - | - | - |
| `snapshots.create(req: CreateRigSnapshotRequest)` | `Snapshot` | `POST /rig-snapshots` |
| `snapshots.list(options?)` | `Snapshot[]` | `GET /rig-snapshots` |
| `snapshots.get(nameOrId)` | `Snapshot` | `GET /rig-snapshots/{ref}` |
| `snapshots.handle(nameOrId)` | `SnapshotHandle` | none |
| `snapshots.previewScrub(rigRef)` | `RigScrubPreview` | `GET /rig-snapshots/scrub-preview` |

A `SnapshotHandle` has `fetch()`, `wait()`, and `delete()`
(`DELETE /rig-snapshots/{ref}`). A fetched `Snapshot` adds `refresh()`.

`create` starts the capture and returns before it finishes. `snapshot.wait()`
polls until the snapshot is `active`, with the same 3-second interval and
15-minute default deadline as rig waits. It throws `AmikaError` if the capture
fails or the deadline passes.

```ts theme={null}
const snapshot = await client.snapshots.create({
  rigRef: "dev-box",
  name: "project-base",
  mode: "scrub_and_delete",
});
await snapshot.wait();
const fork = await client.rigs.create({ snapshot: snapshot.snapshot });
```

`mode` defaults to `scrub_and_delete`, which removes Amika-injected secrets,
captures the cleaned filesystem, and deletes the source rig. `full` keeps the
source rig and captures everything, including credentials. Some providers,
including your own hosts, support only `scrub_and_delete`, and the server
rejects `full` there. `previewScrub` lists the file paths and environment
variable names a scrub would remove, never their values.

`list({ repositoryId, sourceRigId })` filters by repository or by source rig.

## Services

Services are a rig's published ports.

| Method | Returns | HTTP |
| - | - | - |
| `services.list({ rigRef }?)` | `RigServiceResource[]` | `GET /rig-services` |
| `services.create(rigRef, req: RigServiceRequest)` | `RigServiceResource` | `POST /rigs/{ref}/services` |
| `services.replace(rigRef, serviceRef, req, by?)` | `RigServiceResource` | `PUT /rigs/{ref}/services/{service}` |
| `services.delete(rigRef, serviceRef)` | `void` | `DELETE /rigs/{ref}/services/{service}` |

* `list` without `rigRef` lists every service in your organization.
* `create` and `replace` reject ports outside 1–65535 and the reserved range
  60899–60999 before sending a request.
* `replace` looks the service up by name by default. Pass `by: "id"` or
  `by: "ref"` to change that. `delete` looks it up by name.

`rig.services` holds a shorter summary of each service, fetched with the rig.

## Secrets

| Method | Returns | HTTP |
| - | - | - |
| `secrets.list()` | `Secret[]` | `GET /secrets` |
| `secrets.create(req: CreateSecretRequest)` | `void` | `POST /secrets` |
| `secrets.update(id, req: UpdateSecretRequest)` | `void` | `PUT /secrets/{id}` |

Listings return metadata, never secret values. The SDK has no method to delete
a generic secret. The HTTP API has one, `DELETE /secrets/{id}`, and you can
also delete secrets in the web UI.

## Agent credentials

Agent credentials are stored Claude or Codex logins that Amika can inject into
rigs.

| Method | Returns | HTTP |
| - | - | - |
| `agentCredentials.create(provider, req: CreateProviderSecretRequest)` | `ProviderSecretSummary` | `POST /secrets/{provider}` |
| `agentCredentials.list(provider)` | `ProviderSecretListItem[]` | `GET /secrets/{provider}` |
| `agentCredentials.delete(provider, id)` | `void` | `DELETE /secrets/{provider}/{id}` |

`provider` is `"claude"` or `"codex"`. Listings never return credential
values.

## Repositories

| Method | Returns | HTTP |
| - | - | - |
| `repositories.list()` | `RemoteRepository[]` | `GET /repositories` |

## Deprecated flat methods

Earlier SDK versions put every method directly on the client. Those methods
still work but are deprecated. Move to the grouped API:

| Deprecated | Use instead |
| - | - |
| `listRigs()`, `createRig()`, `getRig()` | `rigs.list()`, `rigs.create()`, `rigs.get()` |
| `startRig()`, `stopRig()`, `deleteRig()` | `rig.start()`, `rig.stop()`, `rig.delete()` |
| `waitForRig()`, `waitForRigStart()`, `waitForRigStop()` | `rig.wait()`, `rig.wait({ status: "stopped" })` |
| `agentSend(name, req)` | `rigs.handle(name).send(req)` |
| `sendAgentSession()`, `listAgentSessions()`, … | `agentSessions.send()`, `agentSessions.list()`, … |
| `listSecrets()`, `createSecret()`, `updateSecret()` | `secrets.list()`, `secrets.create()`, `secrets.update()` |
| `createProviderSecret()`, `listProviderSecrets()`, `deleteProviderSecret()` | `agentCredentials.create()`, `.list()`, `.delete()` |
| `listRigSnapshots()`, `createRigSnapshot()`, … | `snapshots.list()`, `snapshots.create()`, … |
| `listRigServices()`, `createRigService()`, … | `services.list()`, `services.create()`, … |
| `listRepositories()` | `repositories.list()` |
| `*Sandbox*` methods and types | The matching `rig` names |

The old wait helpers keep their original behavior. They check provisioning
state only, without checking setup, and have no total deadline. Use
`wait()` for bounded waits that also check setup.

The SSH methods (`getSSH`, `revokeSSH`), the session-record methods
(`createSession`, `listSessions`, `getLatestSession`, `getSession`,
`updateSession`), `extractAgentAuthError`, and `StaticTokenSource` have been
removed. For SSH, use the CLI. See [SSH and connect](https://docs.amika.dev/guides/ssh-and-connect.md).

## See also

> [card] [Types](https://docs.amika.dev/sdks/typescript/types.md)
>
> Request and response interfaces.

> [card] [Errors](https://docs.amika.dev/sdks/typescript/errors.md)
>
> Error classes and wait failures.


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