For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

A session is one running instance of an environment. It lives from the moment you create it until you remove it, and it owns the sandbox it runs in, its event history, and its place in your team’s active session count.

Inside a session, a run is a single turn: the agent receives input, works, and stops. One environment can have many sessions, and one session accumulates many runs.

The distinction matters because each level has different controls. You create environments and reuse them. You pause, resume, fork, and remove sessions. You start, watch, and cancel runs.

Session Identity

Every session has a server-assigned ID beginning with sess_ and a name that is unique within your team. Commands accept either. If you do not supply a name, Harness Runtime generates one.

A session also records which adapter it uses, which cannot change after creation. To run a different agent, create a new session.

Session States

Provisioning, ready, and paused sessions all count toward your team’s limit on active sessions. Removing a session is what releases the slot. Pausing does not.

A session reaches the ready state when the sandbox reports that it is up, which can be marginally before the agent process inside it finishes starting. The first prompt after a cold start may wait a moment longer than the state suggests.

Runs

A run begins when the agent receives input and ends when it completes or fails. Everything the agent does in between, including model calls, tool calls, file edits, and approval requests, belongs to that run and carries its run ID in the event stream.

Sending input to a session whose last run ended in a terminal state returns a conflict error rather than starting a new turn. Start a new session to continue the work.

Only one run is active at a time in a session. Several platform operations wait for the boundary between runs: a session does not pause while a run is working, and you cannot checkpoint or fork mid-run. See Checkpoint, Fork, and Roll Back Sessions.

Pausing and Resuming

Pausing freezes the sandbox in place. Processes, memory, and the workspace filesystem are all preserved, and resuming returns the agent to the point it stopped. Compute charges stop while a session is paused.

Sessions pause for three reasons: you pause them, they go idle, or your team’s prepaid balance reaches $0.

Idle sessions pause automatically after 15 minutes without activity. A session never auto-pauses in the middle of a run, and activity resets the timer.

You do not need to resume a session explicitly before using it. Sending input to a paused session resumes it and delivers the input. The exception is a session paused for a $0 balance, which stays paused until the balance is topped up.

Session Limits

Each team can have a limited number of active sessions at once. Creating a session past the limit returns a conflict error naming the cap. Remove a session you no longer need, then create the new one. Pausing sessions you are not using saves compute charges but does not free a slot.

Reaching Into a Running Session

Most of your interaction with a session goes through the agent. Several commands bypass the agent and act on its sandbox directly, which is useful for inspecting state or moving data the agent does not need to reason about.

• doctl harness-runtime exec runs a single command and returns its output and exit code. Each call is independent, so a directory change does not carry to the next one.
• doctl harness-runtime files ls and files cat browse and read files under the workspace.
• doctl harness-runtime upload and download transfer files and directories in either direction. See Transfer Files.
• doctl harness-runtime port-forward tunnels a local port to a port inside the sandbox, which lets you open a development server the agent started. See Forward Ports.

These commands act on the sandbox regardless of what the agent is doing. They do not wait for a run to finish, and they are not governed by the agent’s permission policy, which applies to actions the agent takes.

For the commands behind these operations, see Manage Sessions.