Help / From the repository to your first session

Getting started.
Step by step.

A local runtime, a copy of your project, a first command. Follow this guide to try ai-guard and understand what you observe.

Explore on GitHub

01 / Before you beginLocal-first

Set up your environment.

Rust 1.99.1, the version pinned in the supplied README, to build the CLI on your machine.
Docker with its Compose plugin, or Podman with a podman compose provider. The default workflow requires a rootless runtime.
Local ports 4000 and 8787 available.
Node 24 only if you are working directly on the frontend. The image build already uses it.

No cloud account is required for this trial. The first build downloads images and dependencies. Choose one stack: Docker and Podman use the same ports here.

These instructions follow the supplied README. This workflow was not run when creating this website; the results below are expected results. Restrictions and compatibility must be verified on your runtime and machine.

Read the repository prerequisites

02 / First trialDocker or Podman

One command.
The complete workflow.

Build and initialize

Get the project from GitHub, then open a terminal at the repository root.

cargo build --release --locked
./target/release/agentsandbox init

init prepares two separate secrets, viewer and runner, and preserves their values if they already exist. Keep the .agentsandbox directory private and use the same configuration directory throughout the installation.

Check, build, and start

With rootless Docker:

./target/release/agentsandbox doctor --runtime docker
./target/release/agentsandbox build --runtime docker
./target/release/agentsandbox up --runtime docker

Or with rootless Podman:

./target/release/agentsandbox doctor --runtime podman
./target/release/agentsandbox build --runtime podman
./target/release/agentsandbox up --runtime podman

Resolve any issues reported by doctor before continuing. A runtime that is not rootless is rejected by default; the README describes the explicit exception for Docker Desktop or a rootful runtime.

Open the local dashboard

Go to http://127.0.0.1:4000. Read .agentsandbox/secrets/viewer locally and enter its contents to sign in. The CLI does not print it.

The runner secret is reserved for the broker. The dashboard lets you view events; commands and approvals go through the CLI.

Run your first command

Replace /chemin/vers/projet with the path to the project you want to copy. For Podman, replace --runtime docker with --runtime podman.

./target/release/agentsandbox run \
  --runtime docker \
  --project /chemin/vers/projet \
  --profile strict \
  --capture-output \
  -- /usr/bin/id

-- marks the start of the worker command. /usr/bin/id is on the initial allowlist; the strict profile keeps networking disabled.

What to look for in the result: the session UUID, its volume, the exit code, and the number of changed files if the scan succeeds. The requested capture retains bounded, redacted stdout/stderr. In the dashboard, review the request, decision, observed start, and result: each stage has a distinct meaning.

Verify and stop

./target/release/agentsandbox verify-audit
./target/release/agentsandbox down --runtime docker

Use --runtime podman if you chose Podman. down preserves audit and session volumes. After a trial that produces files, export them to a new destination outside the original project.

Read the export procedure

03 / Something blocking you?

Find your
next step.

The runtime or Compose is unavailable

Run doctor again with your chosen runtime. Check that the runtime is running and its Compose provider is installed. If the runtime is missing, the broker does not fall back to executing the workload command on your host.

Docker Desktop is rejected because it is not rootless

This rejection is the default behavior. If you choose this exception, the README requires --allow-rootful-runtime on doctor, build, up, and every affected run. These sessions record runtime.security_downgrade. Docker Desktop's VM does not prove that the runtime is rootless.

Read the full exception

The dashboard will not open or rejects sign-in

Check that your chosen stack has started and ports 4000 and 8787 are available. Do not run both stacks together. To sign in, use viewer from the same configuration directory, never runner.

After secrets are refreshed, up recreates the services to mount them again. Finish active jobs before doing this: it interrupts connections to the collector.

The policy denies my command

The strict profile checks the exact invocation against the allowlist; it does not allow arbitrary programs. Review the decision before changing your request. For an invocation that needs review, review can request approval tied to the full SHA-256 hash. An explicit denial remains blocking, and without a terminal an approval request stays pending.

Understand the three profiles

Actions, metrics, or provider outputs are missing

The generic image does not include any provider CLIs. Installing them is optional, with exact versions to select and verify. The Codex and Claude parsers described in the README process bounded stdout at the end of a session; they do not reconstruct native subagents.

Output reported by an agent is not an independent observation. An unavailable metric remains “Unknown”: missing does not mean zero. The Native / Observed / Generic levels describe integration, not a guarantee based on the provider's name.

Read the observation limits

An unavailable collector prevents a launch

The broker needs the collector to authorize and record an execution. Audit unavailability blocks the workflow, even though the dashboard is optional. Check the runtime and stack status before trying again; see the operations documentation for diagnosis and recovery.

Open the operations documentation

04 / Going furtherApache-2.0

The code and its evidence,
in one place.

The repository brings together the code, procedures, and validation references. Check the current status before extending the trial to your environment or a provider.

Getting started.Step by step.