Skip to content

feat(shell): native docker-run-style interactive shell (agentos-shell) #1547

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NathanFlurry merged 1 commit into from
Jun 27, 2026
Merged

feat(shell): native docker-run-style interactive shell (agentos-shell) #1547

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Agent OS is the agent-facing wrapper around secure-exec. It provides ACP session
- Keep generic runtime, kernel, VFS, language execution, generic registry software, and packaged agent definitions/adapters in secure-exec.
- Agent OS owns ACP, sessions, toolkit semantics, quickstarts, docs, and the AgentOs facade.
- Call OS instances VMs, never sandboxes.
- Keep root `package.json` scripts limited to Turbo orchestration; put repo-specific commands in `justfile` recipes.
- The protocol has no backwards compatibility. Clients and the sidecar ship in same-version lockstep, so never add protocol or config versioning, runtime negotiation, fallbacks, or converters. Configs such as `CreateVmConfig` carry no `version` field; the single same-version wire handshake is the only version check. Change the protocol freely and update both sides together.

## Development
Expand Down
36 changes: 9 additions & 27 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 8 additions & 8 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,16 @@ repository = "https://github.com/rivet-dev/agent-os"
# normal crates.io dependencies so CI/publish builds do not need a sibling
# checkout.
[workspace.dependencies]
agentos-bridge = { package = "secure-exec-bridge", version = "0.3.2" }
agentos-bridge = { package = "secure-exec-bridge", path = "../secure-exec/crates/bridge", version = "0.3.0-rc.1" }
agentos-protocol = { path = "crates/agentos-protocol", version = "0.2.0-rc.3" }
agentos-sidecar = { path = "crates/agentos-sidecar", version = "0.2.0-rc.3" }
agentos-sidecar-browser = { path = "crates/agentos-sidecar-browser", version = "0.2.0-rc.3" }
agentos-kernel = { package = "secure-exec-kernel", version = "0.3.2" }
agentos-execution = { package = "secure-exec-execution", version = "0.3.2" }
agentos-v8-runtime = { package = "secure-exec-v8-runtime", version = "0.3.2" }
secure-exec-client = { version = "0.3.2" }
secure-exec-bridge = { version = "0.3.2" }
secure-exec-sidecar = { version = "0.3.2" }
secure-exec-vm-config = { version = "0.3.2" }
agentos-kernel = { package = "secure-exec-kernel", path = "../secure-exec/crates/kernel", version = "0.3.0-rc.1" }
agentos-execution = { package = "secure-exec-execution", path = "../secure-exec/crates/execution", version = "0.3.0-rc.1" }
agentos-v8-runtime = { package = "secure-exec-v8-runtime", path = "../secure-exec/crates/v8-runtime", version = "0.3.0-rc.1" }
secure-exec-client = { path = "../secure-exec/crates/secure-exec-client", version = "0.3.0-rc.1" }
secure-exec-bridge = { path = "../secure-exec/crates/bridge", version = "0.3.0-rc.1" }
secure-exec-sidecar = { path = "../secure-exec/crates/sidecar", version = "0.3.0-rc.1" }
secure-exec-vm-config = { path = "../secure-exec/crates/vm-config", version = "0.3.0-rc.1" }
vbare = "0.0.4"
vbare-compiler = { package = "rivet-vbare-compiler", version = "0.0.5" }
1 change: 1 addition & 0 deletions TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# TODO

- Move root-level npm scripts that are not Turbo orchestration into `justfile` recipes. Keep Turbo commands such as `build`, `start`, `test:watch`, and `check-types` in `package.json`; migrate wrapper/utility scripts such as `test`, `test:migration-parity`, `test:post-python-parity`, `lint`, `fmt`, and `shell`.
- Add OCI import/export support for overlay filesystem layers and snapshots after phase 1. The phase-1 API should only guarantee the bundled base filesystem artifact and the internal snapshot export/import format.
- Run the full secure-exec registry native-kernel suite after rebuilding the WASM command artifacts. `../secure-exec/registry/tests/smoke.test.ts` skipped in this pass because the local `../secure-exec/registry/native/target/wasm32-wasip1/release/commands` binaries were not present, so the new `createKernel` sidecar-backed path is only verified by package-level builds plus targeted core tests right now.
- Expand verification for the new sidecar-backed kernel compatibility surface around `socketTable`/`processTable` observability and browser runtime end-to-end specs. The source builds are green and targeted tests passed, but the deeper integration suites were not exercised in this pass.
3 changes: 3 additions & 0 deletions crates/client/src/shell.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,9 @@ impl AgentOs {
.command
.clone()
.unwrap_or_else(|| DEFAULT_SHELL_COMMAND.to_string());
options
.env
.insert(String::from("AGENTOS_EXEC_TTY"), String::from("1"));
let execute = wire::ExecuteRequest {
process_id: process_id.clone(),
command: Some(command),
Expand Down
10 changes: 5 additions & 5 deletions examples/quickstart/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,11 @@
"sandbox-agent": "^0.4.2",
"dockerode": "^4.0.9",
"get-port": "^7.1.0",
"@agentos-software/git": "catalog:",
"@agentos-software/claude-code": "catalog:",
"@agentos-software/opencode": "catalog:",
"@agentos-software/pi": "catalog:",
"@secure-exec/s3": "catalog:",
"@agentos-software/git": "link:../../../secure-exec/registry/software/git",
"@agentos-software/claude-code": "link:../../../secure-exec/registry/agent/claude",
"@agentos-software/opencode": "link:../../../secure-exec/registry/agent/opencode",
"@agentos-software/pi": "link:../../../secure-exec/registry/agent/pi",
"@secure-exec/s3": "link:../../../secure-exec/registry/file-system/s3",
"zod": "^4.1.11"
},
"devDependencies": {
Expand Down
18 changes: 16 additions & 2 deletions justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,22 @@ secure-exec-set-version VERSION:
agentos-pkgs-set-version VERSION:
node scripts/secure-exec-dep.mjs set-agentos-pkgs-version "{{ VERSION }}"

dev-shell *args:
pnpm --filter @rivet-dev/agentos-dev-shell dev-shell -- "$@"
install-shell:
#!/usr/bin/env bash
set -euo pipefail
pnpm --filter @rivet-dev/agentos-shell build
global_bin_dir="$(pnpm config get global-bin-dir)"
if [[ -z "$global_bin_dir" || "$global_bin_dir" == "undefined" ]]; then
global_bin_dir="${PNPM_HOME:-/tmp/pnpm}"
fi
mkdir -p "$global_bin_dir"
for package in @rivet-dev/agentos-shell @rivet-dev/agent-os-shell @rivet-dev/agentos-workspace; do
PATH="$global_bin_dir:$PATH" pnpm --global remove "$package" >/dev/null 2>&1 || true
done
(cd packages/shell && PATH="$global_bin_dir:$PATH" pnpm link --global)

shell *args:
NODE_OPTIONS="--no-deprecation ${NODE_OPTIONS:-}" pnpm --filter @rivet-dev/agentos-shell exec tsx src/main.ts -i -t "$@"

# Run the agentos-sdk.dev site (landing + /docs) locally with hot reload
docs:
Expand Down
14 changes: 7 additions & 7 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@
"scripts": {
"start": "npx turbo watch build",
"build": "npx turbo build",
"test": "pnpm --dir packages/core build && pnpm --dir packages/dev-shell build && pnpm --dir packages/dev-shell check-types && pnpm --dir packages/dev-shell test && npx turbo test --concurrency=1 --filter='!@rivet-dev/agentos-dev-shell'",
"test": "pnpm --dir packages/core build && npx turbo test --concurrency=1 --filter='!@rivet-dev/agentos-shell'",
"test:migration-parity": "pnpm --dir packages/core exec vitest run tests/migration-parity.test.ts --reporter=verbose",
"test:post-python-parity": "pnpm --dir packages/core build && pnpm --dir packages/core exec vitest run tests/agentos-base-filesystem.test.ts && pnpm --dir packages/dev-shell exec vitest run test/dev-shell.integration.test.ts",
"test:post-python-parity": "pnpm --dir packages/core build && pnpm --dir packages/core exec vitest run tests/agentos-base-filesystem.test.ts",
"test:watch": "npx turbo watch test",
"check-types": "npx turbo check-types --concurrency=1",
"lint": "pnpm biome check .",
Expand All @@ -23,11 +23,11 @@
"@copilotkit/llmock": "^1.6.0",
"@mariozechner/pi-coding-agent": "^0.60.0",
"@rivet-dev/agentos-core": "workspace:*",
"@agentos-software/claude-code": "catalog:",
"@agentos-software/codex": "catalog:",
"@agentos-software/common": "catalog:",
"@secure-exec/core": "catalog:",
"@agentos-software/pi": "catalog:",
"@agentos-software/claude-code": "link:../secure-exec/registry/agent/claude",
"@agentos-software/codex": "link:../secure-exec/registry/agent/codex",
"@agentos-software/common": "link:../secure-exec/registry/software/common",
"@secure-exec/core": "link:../secure-exec/packages/core",
"@agentos-software/pi": "link:../secure-exec/registry/agent/pi",
"@types/node": "^22.19.15",
"jszip": "^3.10.1",
"pdf-lib": "^1.17.1",
Expand Down
4 changes: 2 additions & 2 deletions packages/agentos-sandbox/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@
},
"dependencies": {
"@rivet-dev/agentos-core": "workspace:*",
"@secure-exec/sandbox": "catalog:",
"@secure-exec/sandbox": "link:../../../secure-exec/registry/tool/sandbox",
"sandbox-agent": "^0.4.2",
"zod": "^4.1.11"
},
"devDependencies": {
"@agentos-software/common": "catalog:",
"@agentos-software/common": "link:../../../secure-exec/registry/software/common",
"@types/node": "^22.10.2",
"typescript": "^5.7.2",
"vitest": "^2.1.8"
Expand Down
2 changes: 1 addition & 1 deletion packages/agentos/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
"test": "vitest run"
},
"dependencies": {
"@agentos-software/common": "catalog:",
"@agentos-software/common": "link:../../../secure-exec/registry/software/common",
"@rivet-dev/agentos-core": "workspace:*",
"@rivet-dev/agentos-sidecar": "workspace:*",
"@rivetkit/react": "0.0.0-feat-dylib-actor-plugin.c44621f",
Expand Down
52 changes: 26 additions & 26 deletions packages/core/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,11 @@
"test": "vitest run --reporter=verbose"
},
"dependencies": {
"@agentos-software/common": "catalog:",
"@agentos-software/common": "link:../../../secure-exec/registry/software/common",
"@aws-sdk/client-s3": "^3.1019.0",
"@rivet-dev/agentos-sidecar": "workspace:*",
"@rivetkit/bare-ts": "^0.6.2",
"@secure-exec/core": "catalog:",
"@secure-exec/core": "link:../../../secure-exec/packages/core",
"@xterm/headless": "^6.0.0",
"better-sqlite3": "^12.8.0",
"croner": "^10.0.1",
Expand All @@ -78,31 +78,31 @@
"@bare-ts/tools": "0.15.0",
"@copilotkit/llmock": "^1.6.0",
"@rivet-dev/agentos-sandbox": "link:../agentos-sandbox",
"@agentos-software/git": "catalog:",
"@secure-exec/google-drive": "catalog:",
"@secure-exec/s3": "catalog:",
"@agentos-software/git": "link:../../../secure-exec/registry/software/git",
"@secure-exec/google-drive": "link:../../../secure-exec/registry/file-system/google-drive",
"@secure-exec/s3": "link:../../../secure-exec/registry/file-system/s3",
"@mariozechner/pi-coding-agent": "^0.60.0",
"@agentos-software/claude-code": "catalog:",
"@agentos-software/codex-cli": "catalog:",
"@agentos-software/codex": "catalog:",
"@agentos-software/coreutils": "catalog:",
"@agentos-software/curl": "catalog:",
"@agentos-software/diffutils": "catalog:",
"@agentos-software/fd": "catalog:",
"@agentos-software/file": "catalog:",
"@agentos-software/findutils": "catalog:",
"@agentos-software/gawk": "catalog:",
"@agentos-software/grep": "catalog:",
"@agentos-software/gzip": "catalog:",
"@agentos-software/jq": "catalog:",
"@agentos-software/opencode": "catalog:",
"@agentos-software/pi": "catalog:",
"@agentos-software/pi-cli": "catalog:",
"@agentos-software/ripgrep": "catalog:",
"@agentos-software/sed": "catalog:",
"@agentos-software/tar": "catalog:",
"@agentos-software/tree": "catalog:",
"@agentos-software/yq": "catalog:",
"@agentos-software/claude-code": "link:../../../secure-exec/registry/agent/claude",
"@agentos-software/codex-cli": "link:../../../secure-exec/registry/software/codex",
"@agentos-software/codex": "link:../../../secure-exec/registry/agent/codex",
"@agentos-software/coreutils": "link:../../../secure-exec/registry/software/coreutils",
"@agentos-software/curl": "link:../../../secure-exec/registry/software/curl",
"@agentos-software/diffutils": "link:../../../secure-exec/registry/software/diffutils",
"@agentos-software/fd": "link:../../../secure-exec/registry/software/fd",
"@agentos-software/file": "link:../../../secure-exec/registry/software/file",
"@agentos-software/findutils": "link:../../../secure-exec/registry/software/findutils",
"@agentos-software/gawk": "link:../../../secure-exec/registry/software/gawk",
"@agentos-software/grep": "link:../../../secure-exec/registry/software/grep",
"@agentos-software/gzip": "link:../../../secure-exec/registry/software/gzip",
"@agentos-software/jq": "link:../../../secure-exec/registry/software/jq",
"@agentos-software/opencode": "link:../../../secure-exec/registry/agent/opencode",
"@agentos-software/pi": "link:../../../secure-exec/registry/agent/pi",
"@agentos-software/pi-cli": "link:../../../secure-exec/registry/agent/pi-cli",
"@agentos-software/ripgrep": "link:../../../secure-exec/registry/software/ripgrep",
"@agentos-software/sed": "link:../../../secure-exec/registry/software/sed",
"@agentos-software/tar": "link:../../../secure-exec/registry/software/tar",
"@agentos-software/tree": "link:../../../secure-exec/registry/software/tree",
"@agentos-software/yq": "link:../../../secure-exec/registry/software/yq",
"@types/node": "^22.10.2",
"pi-acp": "^0.0.23",
"sandbox-agent": "^0.4.2",
Expand Down
30 changes: 17 additions & 13 deletions packages/core/src/agent-os.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,7 +347,7 @@ interface AcpTerminalEntry {
interface ShellEntry {
handle: ShellHandle;
dataHandlers: Set<(data: Uint8Array) => void>;
exitPromise: Promise<void>;
exitPromise: Promise<number>;
}

export type RootLowerInput =
Expand Down Expand Up @@ -2698,7 +2698,7 @@ export class AgentOs {
private _closedShellIds = new BoundedSet<string>(
CLOSED_SHELL_ID_RETENTION_LIMIT,
);
private _pendingShellExitPromises = new Set<Promise<void>>();
private _pendingShellExitPromises = new Set<Promise<number>>();
private _shellCounter = 0;
private _acpTerminals = new Map<string, AcpTerminalEntry>();
private _acpTerminalCounter = 0;
Expand Down Expand Up @@ -3142,17 +3142,17 @@ export class AgentOs {
}

/** Write data to a process's stdin. */
writeProcessStdin(pid: number, data: string | Uint8Array): void {
writeProcessStdin(pid: number, data: string | Uint8Array): Promise<void> {
const entry = this._processes.get(pid);
if (!entry) throw new Error(`Process not found: ${pid}`);
entry.proc.writeStdin(data);
return entry.proc.writeStdin(data);
}

/** Close a process's stdin stream. */
closeProcessStdin(pid: number): void {
closeProcessStdin(pid: number): Promise<void> {
const entry = this._processes.get(pid);
if (!entry) throw new Error(`Process not found: ${pid}`);
entry.proc.closeStdin();
return entry.proc.closeStdin();
}

/** Subscribe to stdout data from a process. Returns an unsubscribe function. */
Expand Down Expand Up @@ -3487,12 +3487,9 @@ export class AgentOs {
const entry: ShellEntry = {
handle,
dataHandlers,
exitPromise: Promise.resolve(),
exitPromise: Promise.resolve(0),
};
const exitPromise = handle.wait().then(
() => undefined,
() => undefined,
);
const exitPromise = handle.wait();
entry.exitPromise = exitPromise.finally(() => {
this._pendingShellExitPromises.delete(entry.exitPromise);
if (this._shells.get(shellId) === entry) {
Expand All @@ -3510,10 +3507,10 @@ export class AgentOs {
}

/** Write data to a shell's PTY input. */
writeShell(shellId: string, data: string | Uint8Array): void {
writeShell(shellId: string, data: string | Uint8Array): Promise<void> {
const entry = this._shells.get(shellId);
if (!entry) throw new Error(`Shell not found: ${shellId}`);
entry.handle.write(data);
return entry.handle.write(data);
}

/** Subscribe to data output from a shell. Returns an unsubscribe function. */
Expand All @@ -3536,6 +3533,13 @@ export class AgentOs {
entry.handle.resize(cols, rows);
}

/** Wait for a shell to exit and return its process exit code. */
waitShell(shellId: string): Promise<number> {
const entry = this._shells.get(shellId);
if (!entry) throw new Error(`Shell not found: ${shellId}`);
return entry.exitPromise;
}

/** Kill a shell process and remove it from tracking. */
closeShell(shellId: string): void {
const entry = this._shells.get(shellId);
Expand Down
Loading
Loading