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/authbridge/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, skip ahead to Give feedback — a pasted error is exactly what we need.

Step 2: watch the traffic​

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

abctl 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 abctl.

In abctl 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​

abctl service status
abctl service stop
abctl service start

Stop and remove​

To stop the traffic for one session, quit abctl 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. If the install failed, the numbers looked wrong, or anything was unclear, we want to hear it.

A half-finished install with the error pasted in is more useful to us than a polished bug report you never sent.