LabGate

Policy-controlled sandboxes for AI coding agents on HPC.

Current Focus

• Primary workflow: labgate claude
• Primary runtime: Apptainer
• HPC default: SLURM tracking enabled by default
• Secondary path: labgate codex (best-effort)

Docs: labgate.dev/docs

Install

npm i -g labgate
labgate init

Notes:

• labgate ui requires host tmux.
• node-pty is optional. If it fails to build on a minimal Linux host, LabGate still works and falls back to non-sticky output.
• Default config path is ~/.labgate/config.json.
• labgate init pre-registers a bundled sample dataset at ~/.labgate/datasets/flowers-iris.

Quick Start

Recommended two-node HPC flow:

1. On the login node, start the dashboard:

labgate ui

2. On a compute node, launch Claude inside the sandbox:

srun --pty bash
cd /path/to/project
labgate claude

If browser auth is not practical over SSH, pass an API key directly:

labgate claude --api-key "$ANTHROPIC_API_KEY"

For local non-SSH, non-SLURM shells, labgate claude auto-starts labgate ui when the UI is not already running.

Direct labgate codex terminal sessions use the outer LabGate container as the default safety boundary, so Codex starts with its inner approvals/sandbox bypassed by default. Set LABGATE_CODEX_STANDARD_PERMISSIONS=1 before launch to keep Codex's standard inner sandbox in direct CLI sessions.

What LabGate Does

• Runs Claude or Codex inside a containerized sandbox
• Mounts the working directory, a persistent sandbox home, configured extra paths, and named datasets
• Hides common credential and secret paths by default
• Applies network policy with host or filtered modes
• Blocks high-risk commands such as mount, umount, mkfs, reboot, and shutdown
• Records audit logs in ~/.labgate/logs/
• Tracks SLURM jobs and exposes MCP integrations for supported LabGate subsystems
• Provides a browser UI and web-terminal control plane with labgate ui
• Ships a bundled flowers-iris sample dataset for first-run dataset workflows
• Lets you edit AGENTS.md / CLAUDE.md from the UI, with a temporary LabGate sandbox-context block injected for active sessions

network.mode=none is rejected for labgate claude and labgate codex.

Key Defaults

| Setting | Default | | --- | --- | | runtime | auto | | image | docker.io/library/node:20-bookworm | | session_timeout_hours | 8 | | network.mode | host | | commands.ensure_commands | ["git"] | | slurm.enabled | true | | slurm.mcp_server | true | | audit.enabled | true | | headless.continuation_in_other_terminals | true | | headless.git_integration | false |

Inspect or change config with:

labgate config path
labgate config show
labgate config get <key>
labgate config set <key> <value>
labgate config reset <key>

CLI Overview

Core session commands:

labgate init
labgate claude [workdir]
labgate codex [workdir]
labgate ui [--port <number> --listen-address <address> --token <string> | --socket <path>]
labgate status
labgate continue [idOrName] [--latest]
labgate stop <id>
labgate restart <id> [--dry-run]
labgate logs [-n|--lines <count>] [--follow]
labgate feedback [message...]

SLURM commands:

labgate slurm status [--state <state>] [--limit <count>] [--search <query>]
labgate slurm job <id>
labgate slurm output <id> [--stderr] [--tail <lines>]
labgate slurm cancel <id>
labgate slurm mcp [--db <path>]

Dataset commands:

labgate dataset list
labgate dataset init <name>

labgate dataset init scans an already-registered dataset entry and stores file count and size metadata in config.

Solution Explorer commands:

labgate explore create --name <name> --repo <path> --eval <command> [options]
labgate explore list [--limit <count>] [--offset <count>]
labgate explore status <experimentId> [-n|--limit <count>]
labgate explore pause <experimentId>
labgate explore resume <experimentId>
labgate explore tick --experiment <id>
labgate explore tree --experiment <id> [--mode best_path|full]
labgate explore leaderboard --experiment <id> [-k|--top <count>]
labgate explore gc --experiment <id> [--yes]
labgate explore retention show --experiment <id>
labgate explore retention set --experiment <id> [retention flags]
labgate explore compare --experiment <id> --run <runId> [--to best|parent|<runId>] [--diff]
labgate explore overview --experiment <id>
labgate explore run --id <runId>
labgate explore mcp [--db <path>]

For Claude/Codex sessions, LabGate can also register dataset, cluster, and SLURM MCP servers inside the sandbox when the relevant integrations are enabled.

Enterprise commands:

labgate license
labgate license install <keyOrFile> [--system|--user|--path] [--overwrite]
labgate register <activationKey> [--server <url>] [--token <token>] [--timeout <ms>] [--system|--user|--path] [--overwrite]
labgate policy validate [file]
labgate policy init [--path <path>] [--institution <name>] [--admin <username>] [--runtime <runtime>] [--force]

For full options, use labgate <command> --help or the docs site.

Apptainer and SLURM Notes

• The primary supported path is login-node labgate ui plus compute-node labgate claude.
• LabGate prefers Apptainer on HPC. If you manage runtime explicitly, prefer apptainer.
• SLURM tracking is enabled by default.
• For Apptainer sessions, LabGate expects host SLURM CLIs such as sbatch and squeue to be available when the session starts.
• If your site uses environment modules, load SLURM before launching LabGate:

module load slurm
labgate claude

• In SLURM job scripts, use relative paths or real host paths for #SBATCH --output and #SBATCH --error, not container-only paths such as /work/....

Shared SIF cache:

labgate config set images_dir /shared/labgate/images

Or with an environment override:

export LABGATE_IMAGES_DIR=/shared/labgate/images

LABGATE_IMAGES_DIR takes precedence over images_dir.

Feedback

labgate feedback
labgate feedback "Short feedback message"
echo "This was great" | labgate feedback

Feedback posts to LABGATE_FEEDBACK_URL when set, or to https://labgate.dev/api/feedback by default. If remote submission fails, LabGate saves feedback locally to ~/.labgate/feedback.jsonl.

Development

npm run setup
npm run verify:quick
npm run verify
npm run test:unit
npm run test:integration
npm run test:e2e:real
npm run dev:claude
npm run release:check

License

License terms: labgate.dev