Run AI coding agents in workspaces
Developers increasingly run AI coding agents that edit files, execute commands, install packages, and call external services on their behalf. An agent doing that on a laptop is largely ungoverned. Running it inside a Citrix SecurSpaces™ workspace puts the same controls around it that already apply to the developer.
Agents are used two ways, and the difference decides how much of this page applies to you:
| Mode | What it looks like |
|---|---|
| Attended | A developer opens their workspace in the Cloud IDE or a local IDE and runs an agent from inside it, watching what it does |
| Unattended | A pipeline or an orchestrator creates a workspace, an agent runs on its own, and the result is collected afterwards |
Attended use is where most teams start, and it needs no special configuration: the workspace a developer already has applies its controls to the agent automatically. Unattended runs need more decisions, and most of this page is about those.
This page is for platform administrators. It covers what an agent can reach, how to keep concurrent runs from colliding, what it costs, and what you can see afterwards.
Why a workspace is the right boundary
An agent inherits the environment it runs in. On an endpoint that means the developer’s credentials, their whole filesystem, and unrestricted network access.
In a workspace, the boundary is already drawn:
- Credentials are brokered, not held. Repository and service credentials are injected at runtime and stay with the platform. An agent uses them without being able to read them out and without them ever landing on the endpoint.
- Egress is policy-controlled. An agent reaches only the destinations the workspace’s network policy allows, so an agent that decides to fetch a package from an unexpected host does not get to.
- The filesystem is scoped. The agent sees the workspace, not the developer’s machine.
- Everything is audited. Agent activity produces the same audit events as developer activity.
Attended agents
A developer runs an agent inside the workspace the same way they would on a laptop: open the workspace, start Copilot, Claude Code, Cursor, or whatever the team uses, and work alongside it. Both connection methods support this — the Cloud IDE in a browser tab, or a local IDE connected over SSH. See Choose how you connect.
Nothing extra is required to govern it. The agent runs as the workspace user, so it inherits the network policy, the brokered credentials, the role, and the clipboard rules that already apply to that developer, and its AI traffic is attributed like any other. An administrator decides those controls once, in the template; the developer does not opt in and cannot opt out.
Two things are worth setting up so that developers are not fighting the environment:
-
Agent tooling belongs in the image or a startup script, not in each developer’s manual setup. CLI
agents installed at a system path, and VS Code extensions supplied as
.vsixfiles, are available the moment a workspace starts. See Manage workspace images. - The model endpoint has to be reachable. An agent that cannot reach its provider fails in ways that look like a broken workspace. Include the endpoint in the network policy, or route it through the gateway.
Note:
Data protection controls are weaker when a developer connects a local IDE over SSH than when they use the Cloud IDE, because content leaves the browser session. Where that matters, govern it by policy. See Layered controls.
Unattended agents
The rest of this section concerns runs that nobody is watching. If your developers only use agents interactively, the controls above are already doing their job.
Isolate one run from another
Agents running in parallel that share a working directory interfere with each other: competing edits, clashing ports, and dependency changes made for one task breaking another.
Give each concurrent run its own workspace. A workspace is a container with its own filesystem, its own process space, and its own network identity, so two runs cannot collide.
Create each one from a workspace template, so that the image, resources, credentials, scripts, and policy are defined once and every run starts identical.
Templates can be managed as code with the Terraform provider. The provider manages templates, projects, users, groups, and organizations — it does not create individual workspaces, so per-run creation uses the API or the UI.
The REST API creates workspaces when a pipeline or an orchestrator does the triggering:
| Endpoint | Purpose |
|---|---|
POST /v1/projects/{project_id}/workspaces/template |
Create a workspace from a template |
POST /v1/projects/{project_id}/workspaces |
Create a workspace from an explicit specification |
POST /v1/projects/{project_id}/workspaces/{ws_id}/state |
Start or pause an existing workspace |
DELETE on the workspace |
Discard the run |
Set the state on create so the workspace comes up running rather than paused, and delete it when the run finishes.
Note:
Isolation is per workspace, not per session inside one. Two agents in the same workspace share a filesystem and will interfere. If concurrency matters, create a workspace for each run.
Start the agent inside the workspace
Creating a workspace does not run anything. SecurSpaces has no API for executing a command in a running workspace, so the agent has to be started from inside. There are two ways to arrange that for a run nobody is attending.
A startup script. A workspace runs a pre-startup script before the IDE comes up and a post-startup script once the workspace is ready. Put the agent invocation in the post-startup script and the workspace begins the run on its own, with no external trigger. This is the option to use for unattended runs. Reserve the pre-startup script for preparation the agent depends on, not for the agent itself, because a failure there can stop the workspace coming up at all.
Startup scripts can be set at three levels, and for agent workloads two of them matter:
| Level | Effect |
|---|---|
| Template | Every workspace created from the template runs the same script. Use when the runs are alike |
| Workspace | The script is set on the individual workspace at creation. Use when each run needs a different command |
The workspace level is what lets an orchestrator vary the work per run. Creating a workspace from a template inherits the template’s script, whereas creating one from an explicit specification accepts a startup script in the request, so the caller can supply the command for that run without maintaining a template for every variation.
For how to configure them, see Where to configure startup scripts.
SSH. Retrieve the workspace’s connection details from the API, connect, and run the command. Use this when the orchestrator needs to decide what to run after the workspace exists, or to collect results when the run ends. See Connect over SSH.
A pipeline-driven run therefore looks like this: create the workspace with a post-startup script that launches the agent, let the run proceed, collect the result, delete the workspace.
Important:
Startup scripts run on every workspace start, not only on the first one. If idle detection pauses a workspace and it is later resumed, the post-startup script runs again. Make the script idempotent, or have it check whether the run has already completed, so that resuming a workspace does not silently start the work a second time.
Decide what an agent can reach
An agent is only as constrained as the workspace it runs in, so build the constraint into the template rather than relying on the agent to behave.
Network egress. Attach a network policy that allows only the destinations the work needs — your repositories, your artifact registry, your model endpoint. An agent cannot exfiltrate to a host the policy does not permit, whatever it is asked to do.
Credentials. Use project resources rather than personal secrets for agent workloads, so the credential belongs to the project and can be rotated or revoked without touching a person’s account. Give the workspace only the resources that task requires.
Permissions. The workspace runs as a user with a role. Give agent workspaces a role with the narrowest permissions that work — see Roles and permissions.
Data protection. Clipboard and workspace app controls apply to an agent session as they do to a developer session. See Layered controls.
Control what it costs
Agent runs consume compute differently from people. They are bursty, they can run unattended, and a loop that does not terminate will keep a workspace busy indefinitely. An attended agent is bounded by the developer’s own session, so this section matters most for unattended runs — with the exception of token spend, which applies to both.
- Idle detection pauses a workspace that stops being used, which is the main protection against a forgotten run billing overnight. See Workspace lifecycle and idle detection.
- Workspace specifications cap CPU, memory, and disk per run. Size agent templates deliberately; an agent does not need a developer’s full workstation.
- Concurrency is what drives node count, not the number of workspaces that exist. See Sizing.
Important:
An agent that runs unattended will not pause itself. Idle detection is what stops an abandoned run consuming a node until someone notices, so confirm it is enabled before you allow unattended runs.
See what happened
Two sources, answering different questions.
Audit records what the agent did on the platform: workspace start and stop, resource access, clipboard and transfer events, and monitored network activity. See Audit.
AI Gateway records what the agent spent. When AI traffic is routed through a gateway, SecurSpaces tags every request with the user, project, and workspace it came from, so token consumption can be attributed rather than arriving as a single unattributed bill. See Configure AI Gateway routing.
That attribution is what makes agent usage manageable: without it you know the total and nothing else.
A workable starting point
If developers are running agents interactively, you are most of the way there already. Confirm three things on the templates they use:
- The network policy allows the model endpoint, as well as your repositories and registry.
- The agent tooling is in the image or a startup script, rather than each developer installing it.
- AI traffic is routed through the gateway, so consumption is attributed rather than anonymous.
For unattended runs, add:
- A template for agent runs, with a specification that fits the workload rather than a developer’s desktop.
- Project-scoped credentials, and no more than the task requires.
- Idle detection confirmed enabled, so an abandoned run does not hold a node.
- The agent invocation in a post-startup script, written to be safe if the workspace is resumed.
- One workspace per concurrent run, deleted when the run finishes.
Start with a small population and one team. The template is the thing to get right — once it is, every run inherits it.