Skip to main content
Version: dev

Quickstart on a laptop

RossoCortex is the data plane of Rossoctl. It runs as one program on macOS or Linux. It is a proxy on the request path of your agent. It shows each model call, each tool call and each agent message as it happens. You do not need Kubernetes.

The traffic stays on your computer. RossoCortex does not send it to Rossoctl or to any other service.

This procedure needs approximately 5 minutes.

Before you start​

You need:

  • macOS or Linux, on amd64 or arm64.
  • An agent. The installer configures Claude Code for you. Any agent operates. See Other agents.

Step 1: install the program​

curl -fsSL https://raw.githubusercontent.com/rossoctl/cortex/main/scripts/install.sh \
  | sh -s -- --claude-code

The script asks for your permission before it changes the settings of Claude Code. It then runs RossoCortex as a background service. The service restarts after a failure and after you sign in again.

note

The address of the script is on the main branch, but the script then runs the copy from the most recent release, so the command does not run unreleased code. To pin or override that, use --ref: --ref=vX.Y.Z selects a release and --ref=main installs the unreleased tip. See Installing an unreleased build.

If the install fails, read Troubleshooting first. It covers a certificate that your agent does not trust, a port that another program holds, and a service that does not start. If your condition is not there, go to Give feedback — a pasted error is exactly what the form asks for.

Step 2: watch the traffic​

Open two terminals. In the first terminal, run the viewer:

agentop observe

In the second terminal, run your agent:

claude

Use Claude Code in the normal way. There is no environment variable to set. The calls of the agent appear in agentop.

In agentop observe, press Enter on a session to see its events. Press Enter on an event to see its full content. Press / to filter the events by a text match. Press q to quit. To learn what the filter matches, read Read the numbers.

RossoCortex reads this traffic. It does not change the traffic until you enable a plugin that changes it.

Step 3: read the numbers​

Each session shows a token count and a cost. To learn what each number means, and how to act on it, read Read the numbers.

Manage the service​

agentop service status
agentop service stop
agentop service start

Stop and remove​

To stop the traffic for one session, quit agentop observe with q and stop your agent. RossoCortex continues to run as a background service.

To stop the service, and to remove it, read Manage the service. The service holds no traffic after a stop. It reads traffic again after you start it.

Other agents​

Any agent operates with RossoCortex. Configure the agent with two values:

  • The proxy address: localhost:47600
  • The certificate authority file: ~/.cortex/ca/ca.crt

Most programs read the HTTP_PROXY and HTTPS_PROXY variables. For the certificate, a program reads NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE or SSL_CERT_FILE.

The Rossoctl CLI can set these variables for you, and remove them when the command ends:

rossoctl authbridge exec --config ./authbridge.yaml -- claude "explain this repo"

See Install the cluster CLI.

Next​

Give feedback​

Tell us when it breaks

Cortex on a laptop is new. Report an install that failed, a figure that looked wrong, or a step that was not clear.

Read Troubleshooting first. It covers the most frequent conditions, and it answers a set of figures that look wrong and are correct.

A half-finished install, with the error in the report, is more useful than a complete report that you do not send.