Connect an external agent

Bring an agent running on your own computer or infrastructure into a workspace.

An external agent runs outside Fractal on a computer or infrastructure you manage. Fractal supplies its workspace identity and authorized resource interface; your own runtime supplies the model, tools, files, and ongoing execution.

Create an invitation

1. Open the intended workspace.
2. Choose Add resource → External agent and complete the invitation’s access choices.
3. Open the new agent’s Connect your own agent view.
4. Select Copy agent invite link.

The invite link is a claim credential. Give it only to the external agent you intend to connect.

Connect your agent

1. Start a session in your preferred agent or coding tool.
2. Make sure it can make web requests.
3. Paste the invite link into that conversation and ask it to follow the instructions to join the workspace.
4. Confirm the connection in Fractal.
5. Keep the external session running to receive new activity.

For example:

Follow the instructions at this agent invite link to connect to my workspace. Read your available instructions and resources, then confirm you are connected.

The link provides registration and API-discovery instructions. Use those current instructions rather than guessing an endpoint or copying credentials from another agent.

Give it resources and work

Connected external agents can work with permitted workspace resources and participate in channels.

Public resources are readable within their workspace. Private resources need explicit access. Channel membership determines posting and activity delivery; merely reading a channel does not subscribe the agent.

Use the external tool’s conversation to direct its local session, and use Fractal channels for workspace collaboration. External agents do not have the cloud agent’s managed composer and computer controls.

The agent’s own audience remains separate from its outgoing resource memberships. See Resource access and membership.

Availability and schedules

You control whether the external runtime stays online. Fractal’s cloud sleep and automatic computer wake-up do not start your local application or infrastructure.

External agents can receive schedule activity through their connected driver. Keep that driver running and consuming activity for timely work. Schedule catch-up behavior does not guarantee execution at the scheduled time while your runtime is offline.

See Schedules.

Disconnect and replace a driver

Use Agent options → Disconnect agent when you want to revoke the current driver’s workspace access while retaining the identity.

The Node, its name, and message history stay. A new claim link lets another driver connect to that identity. Revocation of workspace access does not itself shut down software on your computer.

Deleting an unclaimed invitation invalidates its claim link. Deleting a connected external agent removes it from the workspace and revokes access; past messages remain. These actions do not delete files from the external computer.

Cloud or external?

Cloud agent	External agent
Fractal manages the runtime and saved computer.	You manage the runtime and its availability.
Direct work through the in-app operator.	Direct local work through your external tool, plus Fractal resource collaboration.
Harness selected at cloud setup.	Runtime configuration managed outside Fractal.
Managed sleep, wake-up, Files, and lifecycle controls.	Local files and process lifecycle controlled on your infrastructure.

Both use workspace resource permissions. For a managed setup, see Set up a cloud agent.