Manage sessions

Each sandbox tracks a set of agent sessions. The full session CRUD surface is SDK-only today; from the CLI you select sessions through agent-send flags.

Prerequisites

A sandbox in the active / running / started state. See Create a sandbox.

CLI: pick or start a session at agent-send time

The CLI doesn’t expose session CRUD directly. To control which session a prompt runs in, use the flags on agent-send.

# Start a fresh session
amika sandbox agent-send dev-box "Plan the migration" --new-session

# Resume a specific session
amika sandbox agent-send dev-box "Continue from earlier" \
  --session-id 3f2a...

To get a list of sessions, use the SDK or call the HTTP API directly. See CLI reference — agent-send for the full flag table.

SDK: full session lifecycle

The SDK exposes create / list / get / get-latest / update on sessions.

Create a session

const session = await amika.createSession("dev-box", {
  agentName: "claude",
  metadata: { feature: "auth-refactor" },
});

List or fetch sessions

const sessions = await amika.listSessions("dev-box");

// Most recent session — returns null if no sessions exist yet
const latest = await amika.getLatestSession("dev-box");

// By id
const one = await amika.getSession("dev-box", session.id);

getLatestSession is the only call where a 404 from the server is normal — it means “no session yet” and the SDK returns null rather than throwing. You don’t need an error handler for this case.

Use a session in `agentSend`

await amika.agentSend("dev-box", {
  message: "Continue from where you left off",
  sessionId: session.id,
});

Update a session

await amika.updateSession("dev-box", session.id, {
  status: "completed",
  metadata: { feature: "auth-refactor", completedAt: new Date().toISOString() },
});

End-to-end example

const sandboxName = "dev-box";

// Create a session for this run
const session = await amika.createSession(sandboxName, {
  agentName: "claude",
  metadata: { task: "Add unit tests" },
});

// Drive the agent inside that session
const res = await amika.agentSend(sandboxName, {
  message: "Add unit tests for the auth module",
  sessionId: session.id,
});

// Mark the session done
await amika.updateSession(sandboxName, session.id, { status: "completed" });

console.log(res.result);

Session shape

interface Session {
  id: string;
  sandboxId: string;
  orgId: string;
  agentName: string;
  status: string;
  startedAt: string;
  endedAt: string | null;
  metadata: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

Get started

Sandboxes

Agents and sessions

Code validation

Credentials

Advanced

Manage sessions

Prerequisites

CLI: pick or start a session at agent-send time

SDK: full session lifecycle

Create a session

List or fetch sessions

Use a session in `agentSend`

Update a session

End-to-end example

Session shape

Next steps

Send a message to an agent

TypeScript SDK reference

​Prerequisites

​CLI: pick or start a session at agent-send time

​SDK: full session lifecycle

​Create a session

​List or fetch sessions

​Use a session in agentSend

​Update a session

​End-to-end example

​Session shape

​Next steps

Send a message to an agent

TypeScript SDK reference

Prerequisites

CLI: pick or start a session at agent-send time

SDK: full session lifecycle

Create a session

List or fetch sessions

Use a session in `agentSend`

Update a session

End-to-end example

Session shape

Next steps