Agent workspaces

An agent workspace gives an agent an identity and a place to work within a provisioned Rubian environment. Operators need to know whether that workspace is available, what activity has occurred and which work still requires attention. Those are separate questions.

Check availability#

Run:

vmos_status

The command displays system connectivity and the reported state of the configured agent workspaces. For each agent, read the state together with the age of its last report. An old report can explain why a workspace is marked degraded even when an earlier operation succeeded.

If the output says the system is not connected, stop the inspection there and follow the environment's startup instructions. The command cannot establish agent health without a working connection. An agent name in the output identifies a configured workspace; it does not, by itself, establish an authenticated connection to a model provider.

Read activity#

watch_vmos(20)

This displays up to the requested number of messages from each available activity stream and returns the total number displayed. The default limit is 40. It consumes pending messages from those streams, so the same activity is not guaranteed to appear in a second call. Use the environment's designated records when you need durable history.

An empty result means no new messages were available to that call. It does not prove that an agent has stopped. Compare it with vmos_status and the expected work before taking action.

Start and message a workspace#

Use the agent names supplied with the environment:

After starting a workspace, inspect vmos_status and its actual response before submitting dependent work. A configured workspace can be available without an authenticated model provider, and a submitted message can remain unprocessed.

The single-agent commands start_agent, stop_agent, agent_status, agent_running? and agent_log(lines: 20) refer to the specific connector configured for that command family. They are not substitutes for controls targeting every agent by name. workspace_status displays its state and can consume a pending output message; watch_agent(n = 30) reads pending connected output or the configured log fallback.

Restart and supervise#

vmos_restart(agent) requests a restart. Inspect vmos_service_state(agent) afterward: requested state and applied state are different. Omitting the agent name broadens the operation to the command's configured scope.

Permissions constrain which workspaces an identity can supervise. Confirm the selected scope before changing a shared environment. Stopping a process under active supervision can lead to its restart; use the service and supervision controls when you intend to change that behavior.

Submit programmatic work#

agent_run(code) submits Ruby code to the configured agent workspace. Its argument is a program, not a natural-language prompt, and submission does not wait for completion. Use this only with code and a destination appropriate to the supplied evaluation.

Packages with the seat interface also provide seat_eval(code, agent: ..., quiet: true) for an evaluated result and seat_call(function, agent: ..., **arguments) for a provisioned operation. Available operations and permissions come from that package. Do not infer a general public API from an internal operation name shown in diagnostic output.

spawn_userspace(title: 'Rubian', geometry: '110x36') and spawn_agent_window can open an additional configured terminal workspace where desktop support is available; headless behavior depends on the package. Seat-only activity helpers such as ticker, tickers and broadcast require the corresponding agent context.

For persistent shared files, task records and handoffs, use Shared work and messaging.

Inspect system work#

The supplied Taskman interface provides a view of work and system state. Keep the selected item, its owner and the scope of a control visible when reviewing it. A machine process, a Rubian job and an agent workspace can refer to related work without sharing the same identifier or lifecycle.

Before stopping anything, identify the work precisely and determine whether another user or service depends on it. Use the appropriate job or service control for the selected item. The background-job reference covers Rubian job IDs; the pilot operations guide covers declared services.

Confirm that the task succeeded#

Healthy availability is evidence that a workspace can participate in work. To establish completion, inspect the requested output: the file, result, application response or other outcome the task was meant to produce. Record an error or unresolved dependency with that output when reporting a problem.

Avoid pasting full activity streams into a public report. They can contain prompts, file contents and application data. A useful support report contains the command, product version, relevant state and a short redacted error.