Web app

Start here and connect

Start here has three tabs: a checklist computed from live data, Connect for repositories and hosted APIs, and API tokens for the CLI, SDK and scripts.

In the web app Start here

When to use this

• On a new workspace, to see what is not set up yet. GitHub sign-in lands you on Connect.
• To find the agents already in a repository or behind an API, without running anything.
• To get a token for a CI job or a script that calls the gateway.

Checklist

/app/start. Every step is computed from the database on each load by GET /api/onboarding; nothing is stored as "done", so the list cannot disagree with the system. The first unfinished step is marked next and also appears at the foot of Overview.

Under the steps, What is connected counts GitHub accounts, agents, traces, decisions, enforced decisions, knowledge boundaries and tiered sources. Two notes follow: content policies start in observe while tool containment ships enforcing, and not every detector is installed in every deployment (the Guardrail tuning tab shows which are).

The "Run it yourself" step is about installing the package for the CLI or your own control plane. It is optional on a hosted workspace: everything else works over HTTP.

Connect

In the web app Start here → Connect

Connect finds agents. For the data they read, see Verified sources. Both options below are read-only, and what they propose is inert until a person approves it on Agents and Policies.

A GitHub repository

Until GitHub is connected, the tab shows a Connect GitHub button. It is the same OAuth flow as sign-in. Once connected, the tab lists every repository the GitHub account can see, with a filter box, an account column (company or personal), the default branch, when it was last updated, and whether it has already been scanned. Scan (or Scan again) posts the repository and its default branch to POST /api/integrations/github/scan.

The gateway downloads the archive of that branch, runs the same static scan as agentfox scan repo on it (source is parsed, never imported or executed), and deletes it. The result appears at the top of the tab: frameworks detected, and how many agents and policies were proposed, with links to review them. Proposed agents appear as Pending review drafts on Agents; proposed policies appear on Policies already in observe mode. The reconnect link re-runs the GitHub grant.

A scanned repository is then monitored: it is scanned again every six hours (and on every push once the GitHub webhook is registered), and what changed becomes a finding. The scan response's summary carries the monitor_id. See Monitor connected sources.

The scope GitHub is asked for is repo, which includes private repositories. That is what lets the scan download one.

A hosted API

Point us at a hosted API needs no repository access. The form has four fields: API endpoint (required), OpenAPI / Swagger spec URL, Docs URL and What does it do?. Connect & scan posts them to POST /api/integrations/hosted-api/scan. The gateway fetches the spec document, never the API itself, turns each operation into a tool, and proposes one draft agent named after the host and one observe-mode policy. With no spec URL, the endpoint is still registered as a draft agent with no known operations. With one, the spec is then fetched again every six hours and new operations, new destructive ones above all, become findings (the summary's monitor_id).

The spec URL must be http or https and resolve to a public address; every redirect is checked the same way. Loopback and private-network addresses are refused unless the gateway runs with AGENTFOX_OUTBOUND_ALLOW_PRIVATE_HOSTS=true, for a self-hosted deployment whose spec lives on its own network. Link-local addresses, including the cloud metadata address 169.254.169.254, are always refused.

The same call over HTTP, against a local gateway's own OpenAPI document (started with AGENTFOX_OUTBOUND_ALLOW_PRIVATE_HOSTS=true, since the spec is on loopback):

curl -s -X POST http://127.0.0.1:8080/api/integrations/hosted-api/scan \
  -H "Authorization: Bearer $AGENTFOX_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{"endpoint_url":"http://127.0.0.1:8080","openapi_spec_url":"http://127.0.0.1:8080/openapi.json","purpose":"local test"}'

{"scan_run_id":"scn_01m469kx28t61akkj5","status":"completed","summary":{"endpoint_url":"http://127.0.0.1:8791","sites":{"tool":182},"agents_proposed":["127-0-0-1"],"policies_proposed":["scan-scn_01m469kx28t61akkj5-hosted-api"]},"agent":"127-0-0-1"}

The tab then shows "Scan of http://127.0.0.1:8080 · completed · Operations found: 182 · Proposed: 1 agent(s), 1 policy/ies". (The output above was captured against a gateway on port 8791.)

A scan from your own machine

agentfox scan repo with --submit sends the redacted result of a local scan to the workspace, using a token from the next section. The proposals land in the same review queues.

export AGENTFOX_API_URL=http://127.0.0.1:8080
export AGENTFOX_API_TOKEN=nom_api_…
agentfox scan repo ./support_bot --submit

…
Submitted. scan scn_01m469n3ft87ygcgz3 — 0 draft agent(s), 2 proposed polic(ies)
— review them in the dashboard.

API tokens

In the web app Start here → API tokens

A token acts as you, with your role, in your workspace. Use it as Authorization: Bearer nom_api_… on any /api/… route, or set it as AGENTFOX_API_TOKEN for agentfox scan repo --submit.

• Generate a token: give it a name that says what it is for ("CI runner"), then Generate token. Unnamed tokens are called self-service. Calls POST /api/tokens.
• Your new token — copy it now: the full value, with a Copy to clipboard button. Only a hash is stored. Leave the page and it is gone; revoke it and generate another.
• The table: name, the first characters of the token, created, expiry countdown, active or revoked. Every GitHub sign-in adds a row named github-login. Listed by GET /api/tokens.
• Revoke takes effect on the next request: POST /api/tokens/{id}/revoke. There is no confirmation step.

What a token minted here looks like to the gateway, then after Revoke:

curl -s http://127.0.0.1:8080/api/me -H "Authorization: Bearer $TOKEN"

{"id":"usr_01m4697abjqq2fkwg0","email":"admin@example.com","name":"Admin","role":"owner","org_id":"org_default","workspace":"org_default"}

{"detail":"invalid, expired or revoked API token"}

On a self-hosted deployment the operator commands do the same against the database:

agentfox admin auth issue admin@example.com --name ci-runner --days 90
agentfox admin auth tokens
agentfox admin auth revoke tok_01m469mm9pt4qcfghd

  state     name            user            role     prefix         expires
  active    ci-runner       admin@examp…    owner    nom_api_kH…    2027-10-05
  active    dashboard-d…    admin@examp…    owner    nom_api_Z1…    2027-10-05

These are user tokens. An agent calling the guard API or the proxy authenticates with its own agent key; see the gateway guide.

Common tasks

What can go wrong

• "Scan failed: …" at the top of Connect. The gateway could not download the repository (no GitHub connection, a revoked grant, an archive over the size limit) or could not fetch the spec. Use reconnect, or check the spec URL loads in a browser. "refusing to fetch the spec" means the URL resolves to a loopback, private or link-local address (see above).
• Connecting GitHub returns a 503. The gateway has no AGENTFOX_TOKEN_ENCRYPTION_KEY, and refuses to store the GitHub token unencrypted.
• The scan proposes nothing. It reads Python, TypeScript and JavaScript and recognises known frameworks. An agent behind a wrapper it does not know is invisible to it; govern it with the SDK instead.
• A hosted-API draft agent shows up as "running and was never registered" in the attention queue. It is a scan proposal; approve or reject it on Agents and the row goes away.

Limits

• The hosted-API scan fetches whatever URL you give it from the gateway's network, with no allow-list and regardless of allow_egress.
• Repository scans read the default branch only; there is no branch picker.
• Token lifetime is fixed at 365 days in the web app.