Agents

An agent is a caller that belongs to your workspace rather than to a person. It has a name, it reaches only the apps you grant it, and it calls them with credentials of its own. Every request it makes shows in the audit log under its name.

Use an agent for anything that calls your apps on its own: an AI agent that reads a dashboard, a nightly job, another service. A bypass token opens one app and stops when the person who made it loses access. An agent can hold several apps, outlives the person who made it, and is managed by the workspace.

Make an agent

forculus agent create acme release-bot

Made release-bot (ag_5k2m9q0d8w1x7c4v). It reaches nothing yet. Grant it an app with `forculus agent grant acme/<app> release-bot`, then mint it a credential with `forculus agent token acme release-bot`.

Any member of the workspace can make one. Names are unique among a workspace’s agents, whatever their case: with release-bot there, forculus agent create acme Release-Bot is refused with This workspace already has an agent called release-bot. Pick another name. The commands below take the name or the id.

In the dashboard, open Agents in the workspace’s menu and select New agent.

Grant it an app

forculus agent grant acme/payroll release-bot --role viewer

The app sees the agent as a viewer or an editor. It takes effect on the agent’s next request. Only someone who can share the app can grant it: the app’s owners, and the workspace’s owners and admins. In the dashboard, it’s the Agents section of the app’s Sharing tab.

An agent gets into an app only through a grant. Being in the workspace, or the app being open to the whole workspace, lets people in, never agents.

Granting an app to an agent grants it to whoever manages the agent, since they can mint its credentials: its maker, and the workspace’s owners and admins. The Sharing tab shows who made each agent.

So an agent made by a member never reaches further than that member can, by any way they’re let in: shared with them, with a group they’re in, or with everyone at their domain. Take the last of those away, or make them a viewer of the app, and the agents they made lose it, or become viewers of it, at the same time. The same goes when an admin is made a member. Agents made by the workspace’s owners and admins keep their grants, since those people manage every agent anyway.

It holds when you grant one too. Granting a member’s agent an app that member can’t open, or editor on an app they can only view, is refused, and nothing changes:

error: An agent reaches no further than the member who made it. Share the app with them first, or grant the agent less.

To take the app away:

forculus agent revoke acme/payroll release-bot

Its next request is refused, and an open WebSocket, stream or download closes within 15 seconds.

Mint a credential

forculus agent token acme release-bot

The secret starts with fca_ and is shown once. We keep only a hash of it. Give it to the agent in its secret settings, never in code: a deploy that has one in its files is refused.

A credential always ends. From the CLI it lasts up to 30 days (--days), and no longer than your CLI session would. Signing out, or revoking that session, doesn’t end it: it’s a credential of its own. Revoke it as below, or every credential and bypass token you made with forculus logout --everywhere --tokens. The dashboard’s New credential offers 7, 30, 90 or 365 days, and asks you to sign in again if you last did more than 15 minutes ago. The API, POST /v1/workspaces/<workspace>/agents/<agent>/credentials, takes expires_in_days from 1 to 365, and 90 when it’s left out.

The agent’s maker and the workspace’s owners and admins mint and revoke its credentials, unless the workspace’s publish policy keeps minting them to the people its owners name. A maker who is removed from the workspace stops managing their agents, and doesn’t get them back if they’re added again. A credential works only while whoever minted it still could: if they leave the workspace, their address falls outside its allowed domains, they lose the role that let them, or their account ends, it stops working and is revoked for good.

To revoke one, by its id from forculus agent list:

forculus agent token acme release-bot --revoke ac_9d2k4m1q8x0w3c7v

It stops working on the next request.

Call an app

The agent sends its credential to the apps domain, with the workspace and the app as the first two parts of the path, as a bypass token does:

curl -H "Authorization: Bearer $FORCULUS_AGENT_CREDENTIAL" https://forculuslabs-apps.tech/acme/payroll/

The app’s own address, https://payroll--acme.forculuslabs-apps.tech, takes only a browser sign-in and refuses a credential, and so does any custom domain the app has. Our edge checks the credential with the control plane on every request and caches nothing.

What your app sees

Each request carries a fresh identity token in X-Forculus-Identity. For an agent, kind is service, the subject is agent: followed by the agent’s id, and agent_name holds its name as it is now. There’s no email. role is the agent’s role on this app. Every SDK takes it as a service, so an app that already handles bypass tokens handles agents too. From version 0.2.0 each SDK also gives you the name, and says whether an agent called: user.agentName and isAgent(user) in Node.js, user.agent_name and user.is_agent in Python, user.AgentName and user.IsAgent() in Go, user.agent_name and user.is_agent() in Rust. Without those, check whether sub starts with agent:. See What you get back.

Decide what an agent may do by sub, never by agent_name. A name can be changed by whoever manages the agent, and once an agent ends its name is free for a new one. The name is there to show.

List agents

forculus agent list acme
forculus agent list acme --all

It lists the live agents. Add --all for the ended ones too, after them. Each agent comes with the apps granted to it that you can see, its credentials and when each last opened something. One whose maker has deleted their account says it was made by a deleted account. --json gives the same as data, with the maker’s address in created_by and maker_deleted set. The Agents page in the dashboard hides ended agents the same way, until you choose Show ended agents.

In the audit log, the requests an agent was let in on name the agent, by the name it had when it made them, and the credential it used, so you can tell its credentials’ use apart and revoke one alone. A refused request names the agent when it’s one of this workspace’s.

Rename an agent

forculus agent rename acme release-bot ship-bot

Its id, its credentials and the apps granted to it stay as they are. Your app sees the new name in agent_name from the agent’s next request.

End an agent

forculus agent end acme release-bot

Ending is for good. Its credentials stop working on their next request, its apps are taken away, and its name is free for a new agent. It leaves the list, and forculus agent list acme --all still shows it. The log keeps what it did. Since it can’t be undone, it asks first. In a script, or anywhere else with no terminal to ask at, add --yes.

Limits

Agents are on every plan. A workspace can have 100 agents at once, and each agent 10 live credentials. A credential lasts at most 365 days. A workspace can make 200 agents, and mint 200 credentials, in any 24 hours. Past a limit you’re told which one, for example:

error: This workspace has 100 agents, the most it can have at once. End one you no longer use first.

For AI agents using the MCP server

forculus mcp has list_agents, create_agent, set_agent_access, rename_agent and end_agent. list_agents lists the live agents, and the ended ones too with all. It has no tool that mints a credential, so a secret never passes through an agent’s conversation. Mint it yourself with forculus agent token or in the dashboard.