Agent identities
Register an agent on a runtime with a harness and a toolbelt, and manage its mandate.
You govern each agent your team runs under its own identity. An agent is one operator on one runtime with one harness. Your laptop running Claude Code is one agent. The same laptop running Codex is a second agent.
Register an agent
- Open Runtimes in a workspace and add a runtime. Give it a name. Oxagen derives the slug from the name: spaces become hyphens, and every other special character is dropped, so "Mac's Laptop" becomes
macs-laptop. - Register the runtime's first agent. Choose a name, a harness, the runtime, and a toolbelt.
- Run the enrollment command the page shows on the runtime's machine.
A runtime that already runs the harness you chose stays in the list, disabled. Hover over it to see which agent holds that pair. The same holds for a harness the chosen runtime already runs.
Registration requires an organization Owner or Admin. It creates the agent, its delegated principal, its default role, its first version, and a credential shown once. Treat that credential separately from an ordinary Oxagen API key. See API authentication.
The enrollment command runs on the runtime's machine, so install the Oxagen app there first. It links the oxagen command onto your PATH. Wrap an agent covers installation and recording.
The newest Oxagen app for each platform
Every version, with SHA-256 checksumsmacOS 12 or newer. Open the .dmg and drag Oxagen to Applications. Builds are not yet notarized, so macOS refuses the first launch. Choose Done, then click Open Anyway in System Settings > Privacy & Security.
- Apple silicon (.dmg)Oxagen_aarch64.dmg
- Intel (.dmg)Oxagen_x64.dmg
Windows 10 or newer, x64.
- Installer (.exe)Oxagen_x64-setup.exe
- Installer (.msi)Oxagen_x64_en-US.msi
x86_64. Install the package for your distribution.
- .deb (Debian, Ubuntu)Oxagen_amd64.deb
- .rpm (Fedora, RHEL)Oxagen.x86_64.rpm
- AppImage (any distribution)Oxagen_amd64.AppImage
On first launch the app links the oxagen and tacho commands onto your PATH, so a new terminal can run them.
On macOS, the app installs new versions on its own and runs them after your next restart. Windows and Linux ask first. How updates work and how to turn them off.
Toolbelt
A toolbelt is the set of tools an agent is shown. Every workspace has an All tools belt, which holds every tool an owner or admin made available. Clone it from Toolbelts on the Agents page's MCP servers tab, then remove servers or turn servers and tools on or off in the clone. A toolbelt narrows what an agent can reach. Roles, mandates, and kill switches still decide each call.
When the workspace has no imported tools, the register form's toolbelt step completes itself and links to the page that imports MCP servers.
Versions
The agent's principal, operator, and harness never change. Its runtime and its toolbelt can. Moving the agent to another runtime (move_agent) or giving it another toolbelt (assign_agent_toolbelt) writes a new agent version. The principal keeps its roles, mandates, credentials, and runs, so a hardware replacement or a cloud migration does not start the agent over.
An agent carries no prompt and no definition file. Steering records tell it what to do, and its toolbelt says what it can reach.
Mandate
Open the agent's mandate to inspect its authority, budget, and rules. Agent roles describes the role ceiling. Registration does not start a scheduled runtime in Oxagen. Your harness runs the work.
Environments
An agent has no environment of its own. A sandbox run gets its secrets from the environment its sandbox runtime names. When the runtime names none, the run gets the workspace's default environment. Several operators share one runtime, so the runtime is the one place that choice is made. See Environments and secrets.