#Computers

A Computer is a connected device, server, or container where an Agent can run work. It provides the operating system, files, credentials, network access, and tools required by an Agent.

#Computer, Runtime, and local service

These terms describe different parts of execution:

• Computer: the connected host. A Computer can expose one or more Runtimes and has its own owner, visibility, status, and task concurrency limit.
• Runtime: a supported Agent execution capability detected on a Computer. Each Runtime identifies a provider and reports its own connection state. An Agent needs a usable Runtime before it can run.
• local service: the background process that runs on the Computer. It registers the Computer, detects Runtimes, sends heartbeats, receives queued runs, prepares directories, starts Agent tools, and reports progress and results.

The local service initiates the connection to the server, so a typical setup does not require an inbound port.

#Connect and register a Computer

Create a one-time install token from the Computers page, then run the registration command on the target Computer:

sharkly computer register --install-token <install-token>

Registration records the Computer in the selected organization and starts or restarts the local service unless the command is told not to. The local service then detects installed Runtimes and reports them with the Computer.

After registration, confirm that the Computer appears and that at least one supported Runtime is available. A connected Computer without a usable Runtime cannot execute Agent work.

#Runtime capability status

Computer detail reports a capability status for each Runtime:

A Computer being online only means that its local service is reporting heartbeats. It does not mean that the selected Runtime can execute a Task. When a run cannot start, check the selected Runtime's capability status before troubleshooting the Computer connection.

#Configure a custom ACP Runtime

If the local service does not detect an execution capability, add a custom ACP Runtime from Computer detail:

1. Configure the Runtime icon, name, and startup command.
2. Save the Runtime and select Test connection.
3. After it is configured, edit those values when needed or delete the custom Runtime when it is no longer used.

Enter only the configuration requested by the product. Do not place passwords, tokens, or other sensitive values in unrelated fields or startup commands.

#ACP adapter isolation

When an ACP adapter lacks a compatible Node.js environment, Sharkly first reuses an existing compatible environment. If one is not available, it can prepare a product-managed isolated execution environment for that adapter only. It does not modify the system-wide Node.js or npm, shell configuration, project directory, or the user's version-manager configuration.

If environment preparation fails, Sharkly keeps the original environment and provides manual repair guidance instead of replacing the existing configuration.

On macOS, if Codex is not installed on its own, installing the ChatGPT desktop app is enough for the local service to register the app's bundled Codex CLI as a Runtime. Prefer a Codex you installed and put on PATH; the app bundle is only a fallback. This does not apply to Windows or Linux.

#Computer commands

Use the sharkly computer command group to inspect and manage registered Computers:

sharkly computer list
sharkly computer show <computer-id>
sharkly computer usage <computer-id> <runtime-id>
sharkly computer activity <computer-id> <runtime-id>
sharkly computer ping <computer-id> <runtime-id>
sharkly computer update <computer-id> <runtime-id>

• list shows Computers registered for the current organization.
• show returns the Computer and its Runtimes.
• usage and activity inspect a specific Runtime.
• ping checks whether a specific Runtime can complete a round trip through the local service.
• update requests a CLI update for a specific Runtime.

Use --organization-id when the selected CLI organization is not the one you want to inspect.

#Status and registration state

A Computer is Online when the server is receiving current heartbeats from its local service. It is Offline when those heartbeats stop.

A Runtime also reports whether it is online or offline. These states are related but not interchangeable: a Computer can be online while no supported Runtime is available, and an Agent cannot run until its selected Runtime is usable.

During first-time setup, the desktop app can also show transitional states such as starting the local service, waiting for registration, or reconnect required. Registration is complete only when the server has accepted the connection and the Computer appears in the organization.

If a Computer is offline or registration stalls, check that:

• the target Computer is powered on and connected to the network;
• the local service is running and authenticated;
• the CLI is current enough to connect;
• the selected Runtime is installed and available to the local service;
• required repositories, credentials, directories, and commands are accessible on that Computer.

#Prevent sleep

Prevent sleep appears only on this computer in the desktop app. It is not available on a shared or remote Computer.

When it is on, the machine stays awake while the display can still sleep under the system settings. This is not keep-display-on. Use it so local tasks and Agent connections are not interrupted by system sleep.

Duration options:

• Always
• 5 minutes
• 30 minutes
• 1 hour
• 2 hours
• 5 hours
• 8 hours

The setting turns off when the duration ends. Changing the duration restarts the timer. Always does not expire.

Keep running with lid closed is a separate option. It appears only on macOS, and only when the system allows it. If the machine is unplugged, the product asks you to connect power first — do not treat the option as already in effect.

#Visibility and ownership

Visibility controls who can see and use a Computer in an organization:

• Personal: available to the owner.
• Organization: available across the organization.
• Space: available through the selected Spaces.

Ownership is separate from visibility. The owner controls the Computer itself, can transfer ownership to another person in the organization, and is the only person who can delete it. Organization or Space administrators may be able to repair shared access settings without becoming the owner.

The owner can also Unbind runtime for one Agent, or Unbind all, from the Agents area on the Computer detail page. This is how the owner reclaims the Computer without deleting it:

• The Agent stays; it is not archived or deleted. This Computer is cleared as its execution target, so it must choose a Computer again before it can run.
• Active runs are cancelled. Assigned tasks need reassignment.
• Unbinding does not grant full edit access to someone else's Agent.

Confirmation copy follows the product UI. Deleting a Computer can still be blocked while an active Agent is bound; unbind first, then delete.

Use Personal visibility for a personal device or private credentials. Use Organization or Space visibility only when the host and its credentials are intended for shared Agent work.

#Allowed Organizations

The owner of a local personal Computer can also control which Organizations may use it:

• All Organizations allows Organizations where the owner is currently a member, including Organizations the owner joins later.
• Selected Organizations allows only Organizations explicitly selected for the Computer.

Only the Computer owner can change this setting. Being an Organization Owner or Admin does not grant control of another person's personal Computer.

Visibility and allowed Organizations are separate restrictions: visibility determines who can see or select the Computer within an Organization, while allowed Organizations determines where that local personal Computer can be used.

#Disk usage and automatic cleanup

Agent runs leave working directories, caches, and artifacts on the Computer. Configure automatic cleanup in the desktop local-service settings or Computer cleanup settings.

The settings include:

• Cleanup frequency (hours)
• Terminal run retention (days)
• Minimum free space (GiB, 0 disables)
• Additional repository cache retention after eligibility (days)

The default is active: terminal runs such as completed or canceled work become eligible after about 7 days. You can also set a minimum free-space threshold (conservative default 10 GiB; 0 turns it off). When free space is below the threshold, cleanup only reclaims the same safe set, preferring larger items.

Automatic cleanup does not remove:

• running or queued work;
• pinned runs;
• failed runs that still need investigation;
• nested Agent caches such as ~/.claude/worktrees.

Restart the local service or re-register the Computer after saving. Do not delete local-service directories you do not understand.

For an immediate check or a one-off cleanup, use the CLI:

sharkly daemon disk-usage
sharkly daemon cleanup
sharkly daemon cleanup --confirm

daemon cleanup is a dry run unless --confirm is present. The desktop policy and the CLI commands complement each other; neither replaces the other.

#Remove a Computer

Deleting a Computer removes its registration and attached Runtimes. Deletion is blocked while an active Agent is still bound to one of those Runtimes. Reassign or archive those Agents first, then delete the Computer as its owner.