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.

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.

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.

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.

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.

Computer, Runtime, and local service#

Connect and register a Computer#

Computer commands#

Status and registration state#