Skip to Content
kosemdocs
GuidesAccess and secrets

Give an agent access

Grant an agent short-lived access profiles or static secrets, approve on-demand access requests, and revoke access immediately.

Let an agent authenticate to GitHub, Google Cloud or AWS through a project access profile, or pass a stored secret (such as an API key) to specific shell commands.

To grant an access profile, you need connections.accessProfiles.issue on the profile (Owner, Connection Admin or Access Profile Accessor). To grant a stored secret, you need secrets.versions.access on the secret (Owner, Secret Manager Admin or Secret Accessor). In both cases you also need write access to the agent (agents.secretGrants.create).

Anyone who can write to an agent can direct it to use what it has been granted. Grant agents only the access their task needs, prefer read-only access profiles with a time limit (TTL), and revoke grants once work finishes.

When you start an agent

  1. In your project, click New agent.
  2. Click the Access picker in the composer strip.
  3. Select one or more Access profiles (with optional scope narrowing and duration) or Secrets.
  4. Selected grants appear as removable chips in the composer strip. Notice that only read-only access profiles carry over automatically onto new project-visible agents; write access profiles and static secrets are never carried over automatically.
  5. Describe the task and start the agent.

On a running agent

  1. Open the agent and click the Access picker in the composer strip.
  2. Add an access profile (optionally narrowed and time-limited) or a stored secret, review who can use it on this agent, and confirm.
  3. To revoke a grant immediately, click the remove button on its chip or open the picker.

On-demand access requests

When an agent hits a task that needs access it doesn't have yet (such as pushing a branch or reading an API key), it can call request_access to pause and ask you in the transcript. An inline Access request card lets you approve (optionally narrowing scope or setting a shorter duration) or deny the request, and the agent continues automatically with the decision.

How the agent uses granted access

  • Access profiles work automatically: kosem configures git, gh, aws, gcloud and standard cloud SDK metadata inside the agent's environment. Credentials are minted on demand through /run/kosem/creds.sock, narrowed to the grant's scope, and redacted automatically from live command output.
  • Static secrets are passed per command: the agent passes a granted secret to a single command via exec's secrets argument (VAR=alias or file:name=alias under /run/kosem/secrets). Values are never persisted in shell state and are redacted from live output.

Each credential issue (connections.IssueCredentialForEnvironment) and secret use (secrets.UseSecretVersion) is recorded in the System Events audit log with the agent, environment and grantor.

Revoke access from an agent

You can revoke a grant in two ways:

  • From the agent: anyone with Owner on the agent, or Owner or Agents Admin on its project, can remove any grant from the composer strip or agent settings.
  • From the resource: an IAM admin of the access profile (connections.accessProfiles.setIamPolicy) or secret (secrets.secrets.setIamPolicy) can open the resource's Agents tab and click Revoke on any agent row, including private agents.

Revoking a grant immediately invalidates cached credentials in the agent's running environment over its tunnel so subsequent commands stop receiving them right away. Already-minted provider tokens remain valid upstream until their short expiry (such as GitHub's 1-hour token), and values already read by a command can't be unread — rotate static secrets if exposed.

On this page