Skip to main content

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.

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;
}

​
Next steps

Send a message to an agent

TypeScript SDK reference