Give AI agents governed access

You’ve decided to let an AI agent touch your infrastructure. Maybe it’s Claude fixing a failing service, Cursor running a migration, or a custom agent doing routine maintenance. The question isn’t whether to give it access, but how to grant that access without handing over a standing key you can’t take back.

This page is the journey for the person making that decision: a workspace admin or team lead introducing an agent. It walks the whole arc—connect the agent, scope it to the task in front of it, keep a human on the approval, watch it work, and read back everything it did—linking each step to the page that covers it in full. If the concept is new to you, first read AI agents for the model, then come back here to wire one up.

The model in one paragraph

An AI agent is a first-class actor in Alpacon, governed the same way a person is: it doesn’t connect to a server directly, it opens a scoped, time-bound, recorded work session and works inside it. But the agent is held to a stricter rule than a human. A person with the Superuser role who requests a session for themselves is approved automatically; an agent’s session always requires a human approval, even when a Superuser makes the request. There is no automatic path for a non-human actor. That single asymmetry is the heart of agent governance in Alpacon—everything below is how you set it up and live with it.

A Superuser’s own session request clears immediately. A session requested by an AI agent does not: it always waits for a person to approve it. See Approvals and Request a session.

Step 1: Connect the agent

Agents reach Alpacon over MCP (Model Context Protocol), and there are two paths:

  • Hosted — point your MCP client at https://mcp.alpacon.io/mcp and sign in through your browser. No install, no API token pasted into a config file; the agent authenticates with your login and inherits your identity, roles, and audit trail.
  • Local — run the Alpacon MCP server yourself with uvx alpacon-mcp, configured with an API token, for setups that prefer a local process.

For Claude Code, the hosted path is a single line:

claude mcp add --transport http alpacon https://mcp.alpacon.io/mcp

On first use the client opens your browser to sign in, and you verify with claude mcp list. Rather than repeat every client’s configuration here, use Getting started with MCP for Claude Desktop, Cursor, VS Code, and the local-server setup, and the MCP reference for the full tool catalog. The point for this journey: connecting an agent hands it no SSH key and no VPN credential—it works through the same governed identity layer as the web console and CLI.

Step 2: Scope it down to the task

Connecting an agent doesn’t grant it anything on its own. Access is bounded in layers, and each layer is something you control before the agent ever runs a command:

  • Workspace membership — the agent acts through an Alpacon identity: a person it works on behalf of, or an application created for automation. It can only ever see the one workspace that identity belongs to.
  • Group-based server eligibility — inside the workspace, group membership decides which servers the identity can even request. A server with no groups assigned to the identity is invisible to it. This is the same join you set up for people; see Control server access.
  • Session scope — to actually do work, the agent opens a work session that declares its intent, the specific servers, the features it needs (web terminal, file transfer, command execution, port forwarding, code editor, privilege elevation), and an expiry. The scope is a hard ceiling: an action outside it is refused, and the session ends on its own when the time is up.

The discipline that makes this work is request per task, not standing breadth. Don’t wire an agent into every group and let it open four-hour all-feature sessions by habit. Give its identity the groups the work actually needs, and let each session ask for just the servers, features, and window that one task requires. Least privilege is the default here—the agent only gets what it asks for, and only for as long as it asked. See Work sessions for the full model.

Step 3: The approval moment

Because an agent’s session always waits for a person, someone on your team sees the request. For a work session, the reviewer opens it from the Approvals queue and sees the requester’s justification, the requested duration, the target servers, and the features being asked for—plus an AI pre-review that recommends a risk level (Low, Medium, High, or Critical), explains its reasoning, and highlights the features it thinks the session needs.

The reviewer isn’t limited to a yes/no. Before approving, they can tighten the scope: add or remove features, add or remove target servers, and attach recommendations the agent’s operator sees before the session starts. So the approval moment is also a scoping moment—an over-broad agent request can be trimmed to exactly what the task warrants and then approved. See Reviewing requests and Request types for what’s adjustable per request type.

For the reviewer’s side of this—how to read an agent request and decide quickly—see the approver’s guide, the counterpart to this page written for whoever holds the queue.

Step 4: Watch it work

Once a session is approved and active, you don’t have to wait for it to end to see what’s happening. Live activity (Superuser only) streams active sessions in real time: a feed of commands as they’re created, run, and finish, terminals opening and closing, sudo requested, granted, or denied, and files moving—filterable by category.

Two things stay in a person’s hands while the session runs:

  • Sensitive actions are held while they happen. Privilege elevation (sudo) and other high-risk actions don’t just run—they’re routed to a human approver, and the agent waits for the decision before proceeding. A misled or jailbroken agent can’t quietly escalate, because there’s no standing privilege for it to reach for.
  • You can intervene. From the live view you can Complete a session to end it immediately, or Revoke one that was approved but shouldn’t proceed. Every command and transfer is recorded as it runs, so nothing is happening off the record.

Step 5: Read back everything it did

When the work is done, the whole session is there to review—which matters more for a non-human actor than a human one, because accountability can’t rest on “I remember what I ran.” Audit keeps the complete record:

  • Sessions — every work session on one list (Session history), with the Operator column naming who actually ran it: a user, an API token, or a service token. You can see who requested it, who approved it, what was in scope, and how it ended.
  • The timeline and recordings — a session’s detail replays a chronological timeline of its commands, terminals, sudo grants, and file transfers, with masked terminal recordings you can play back. See After a session.
  • AI post-analysis — once a session ends, Alpacon adds an AI risk analysis: a risk level, a plain-language summary, an attack-chain and threat check, and recommended verifications. This is the deeper, after-the-fact judgment that complements the live feed in Step 4.

Because people, pipelines, and agents all run through the same work-session model, their activity lands on one timeline. When someone asks “what happened on prod-web-1 last night?”, the answer is a single record that mixes human commands, agent actions, and CI runs—not separate logs to stitch together. That shared timeline is what makes an agent’s actions accountable to the same standard as a person’s.

What an agent can’t do

The governance model closes the obvious escape hatches. An agent cannot approve its own work: a session it requests always needs a human, even when the requesting identity is a Superuser. It cannot approve through its own channel either—a request can’t be approved from the same channel it was submitted from, so an agent working through the CLI or MCP can’t turn around and clear its own request; approval happens in the web console or Slack, by a Superuser. And it cannot stand in for a person’s identity checks: steps that require a human’s multi-factor verification can’t be satisfied by an agent, so they escalate to a real person instead of proceeding. See sudo with MFA.

One nuance worth understanding, not hiding: the work-session gate depends on how the agent authenticates. When an agent connects through browser sign-in (MCP OAuth)—the recommended path above—infrastructure-mutating actions like running commands and transferring files must be linked to an active, approved work session. A static API token follows a different path that isn’t bound to a work session, so treat tokens as owned, audited automation credentials, not as a way to skip the gate: issue them to an application so their activity is scoped and attributed, and keep interactive agents on browser sign-in. See the MCP reference for exactly which calls are session-scoped.

Where to go next

Last updated: