Agentuity Documentation

Agentuity Coder runs AI-assisted coding sessions in cloud sandboxes. Each session connects an AI agent (powered by Pi) to a managed environment where it can write code, run builds, execute tests, and iterate autonomously, while you watch or collaborate in real time.

Standalone Package

Use the @agentuity/coder package to manage sessions from any Node.js or Bun application without the full runtime.

When to Use Coder

Approach	Best For
Coder sessions	Autonomous coding tasks in isolated sandboxes, remote pair programming with AI
Claude Code plugin	AI-assisted development in your local project via Claude Code
OpenCode plugin	Multi-agent team for complex tasks in OpenCode
Sandbox service	Running arbitrary code or scripts in isolated environments

Use Coder when you want an AI agent to work independently in a cloud sandbox: building features, fixing bugs, or exploring code, without tying up your local environment.

Managing Sessions

Method	Best For
SDK (`CoderClient`)	Programmatic session management from agents, scripts, or external apps
CLI (`agentuity coder`)	Interactive session management and local development
Web App	Observing sessions, viewing transcripts, browsing history

Hub URL is discovered when not explicitly set

Coder has HTTP endpoints, but no single static base URL. If neither url nor AGENTUITY_CODER_URL is set, clients call the Agentuity API to discover your org's Hub address, then route session and workspace requests to that Hub. @agentuity/coder and agentuity coder handle discovery, auth, and routing for you.

How It Works

A Coder session has three components:

Hub: Orchestration server that manages session lifecycle, tools, and real-time communication via WebSocket
Agent: An AI coding agent that connects to the Hub and executes tasks
Sandbox: An isolated cloud environment where the agent writes, builds, and tests code

Sessions support multiple participants: the primary agent, sub-agents that split work, and observers that stream the session transcript in real time.

SDK Usage

Install the standalone package:

bun add @agentuity/coder

Creating and Listing Sessions

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Create a new session
const session = await client.createSession({
  task: 'Implement OAuth login with GitHub provider',
  workflowMode: 'standard',
  tags: ['auth', 'feature'],
});
console.log(`Session created: ${session.sessionId}`);
 
// List active sessions
const { sessions } = await client.listSessions({ limit: 10 });
for (const s of sessions) {
  console.log(`${s.sessionId}: ${s.label} (${s.status})`);
}

Session Operations

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Get session details
const session = await client.getSession('codesess_abc123');
 
// Update a session
await client.updateSession('codesess_abc123', {
  label: 'Auth feature - phase 2',
  tags: ['auth', 'feature', 'phase-2'],
});
 
// Archive a completed session (preserves transcript for replay)
await client.archiveSession('codesess_abc123');
 
// Resume a paused session (wakes the sandbox)
await client.resumeSession('codesess_abc123');
 
// Permanently delete a session
await client.deleteSession('codesess_abc123');

Session Data and Replay

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
const sessionId = 'codesess_abc123';
 
// Get the full session replay (transcript + events)
const replay = await client.getReplay(sessionId);
 
// List participants in a session
const participants = await client.listParticipants(sessionId);
 
// Get event history
const events = await client.listEventHistory(sessionId, { limit: 50 });
 
// Check loop state (for autonomous sessions)
const loopState = await client.getLoopState(sessionId);

Workspaces and Skills

Workspaces group repositories and skills into reusable configurations that can be attached to sessions.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient();
 
// Create a workspace
const workspace = await client.createWorkspace({
  name: 'Auth System',
  description: 'OAuth and session management',
});
 
// Save a reusable skill
const skill = await client.saveSkill({
  repo: 'my-org/my-skills',
  skillId: 'code-review',
  name: 'code-review',
  description: 'Review code for security issues',
  content: 'Review the changes for OWASP top 10 vulnerabilities...',
});
 
// List saved skills
const { skills } = await client.listSavedSkills();

Client Configuration

The client picks one of two modes based on what you provide.

Discovery mode (recommended). Omit url and AGENTUITY_CODER_URL; the client calls the Agentuity API to resolve your org's Hub. region is only consulted in this mode.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient({
  apiKey: 'agentuity_sk_...',           // Override AGENTUITY_SDK_KEY
  region: 'usc',                        // Region used when discovering the Hub
  orgId: 'org_...',                     // Organization scope
});

Explicit mode. Set url (or AGENTUITY_CODER_URL) to a known Hub. Discovery is skipped, and region has no effect.

import { CoderClient } from '@agentuity/coder';
 
const client = new CoderClient({
  url: 'https://coder.example.com',     // Explicit Hub URL — skips discovery
  apiKey: 'agentuity_sk_...',
  orgId: 'org_...',
});

The client resolves the Hub URL in this order:

options.url (explicit)
AGENTUITY_CODER_URL environment variable
Auto-discovery via the Agentuity API

Most apps only need the API key. Set AGENTUITY_SDK_KEY and let the client discover the rest.

CLI Usage

# Start a coding session
agentuity coder start
 
# Start with a task in a sandbox
agentuity coder start --sandbox "Build an auth system" --repo https://github.com/org/repo
 
# List active sessions
agentuity coder list
 
# Inspect a session
agentuity coder inspect codesess_abc123
 
# Connect to an existing session
agentuity coder start --remote codesess_abc123

See Coder CLI Commands for the full command reference.

Session Modes

Running agentuity coder start with no extra flags launches a local TUI session. Using --sandbox <task> creates a cloud sandbox session with the provided task description. Using --remote <session_id> connects to an existing remote session.

Mode	Description
`tui`	Interactive agent in your local terminal
`sandbox`	Agent runs in a cloud sandbox; observe via CLI or web
`remote`	Attach to a running cloud session by ID

Session Lifecycle

State	Description
Created	Session initialized, waiting for agent to connect
Active	Agent is connected and working
Idle	Agent has finished the current task, waiting for new instructions
Paused	Agent disconnected, sandbox suspended. Resume with `resumeSession()` or `--remote`
Archived	Session ended, transcript preserved for replay

Connecting via Plugins

The Claude Code and OpenCode plugins integrate with the Coder ecosystem:

Claude Code: The base Agentuity plugin (/install agentuity) provides skills for deploying and building with the SDK. The separate agentuity-coder marketplace plugin adds multi-agent teams, persistent memory, and cadence mode
OpenCode: The @agentuity/opencode plugin provides a multi-agent team (Lead, Scout, Builder, etc.) with background tasks and workspace integration

Next Steps

CoderClient Reference: Full method reference for @agentuity/coder
Coder CLI Commands: Full command reference
@agentuity/coder Package: Install and constructor overview
Sandbox: Manage sandbox environments directly
Claude Code Plugin: AI-assisted local development