Repository navigation
Docs: Running Cortex on a remote machine - #1607
Conversation
Cortex stays loopback-bound and unauthenticated; an encrypted tunnel (ssh -L, kubectl port-forward, oc port-forward with one project per user) is the only way in, and agentop connects with --endpoint. Verified end to end on a Lima VM: systemd user unit, session API, erase through the tunnel, agents-local traffic through the remote forward proxy and TLS bridge, agentop observe against the remote endpoint. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Hai Huang <huang195@gmail.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 18 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
NODE_EXTRA_CA_CERTS adds to Node's roots, so the bare remote ca.crt is right for it — but the aside sent SSL_CERT_FILE readers at the same file, which replaces the whole store and would break every direct TLS call. The server's bundle.crt is no substitute (it carries the server's roots); point at building a local bundle and at agents/any-agent.md's add/replace table. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Hai Huang <huang195@gmail.com>
clawgenti
left a comment
clawgenti
left a comment
There was a problem hiding this comment.
Summary
Clear, accurate guide. I checked its claims against main: loopback pins 47600/47601/47602/47604 (cmd/cortex/local.go), ca_dir = ~/.cortex/ca, bundle.crt = bridge CA + server platform roots (core/tlsbridge/bundle.go), and the DELETE guard accepting a loopback Host with no Origin (core/sessionapi/clear.go). All match. I have three non-blocking comments: the "security model unchanged" line needs a shared-host caveat, agentop service would overwrite the hand-written unit rather than manage it, and the ExecStart path should match where install.sh puts the binary.
One optional format nit: the body uses ## What rather than ## Summary.
Author: huang195 (MEMBER — maintainer)
Areas reviewed: Docs (README.md, docs/README.md, docs/remote.md), security claims
Agent/IDE config (.claude/.vscode): none
Commits: 2 commits, all signed-off: yes
CI status: DCO, pre-commit, YAML/shell lint, action pinning, Trivy and PR-title checks pass. Go CI, CodeQL and image builds were still pending when I reviewed; this PR only changes docs.
| home server, a cluster pod — it is the same process with the same binding, and the | ||
| machine is reached over an encrypted tunnel that carries loopback across the network. | ||
| Your SSH key or cluster identity is the authentication; Cortex never learns it is | ||
| remote, and nothing about its security model changes. |
There was a problem hiding this comment.
suggestion: "nothing about its security model changes" holds for a single-user box, but there is one real difference from a laptop. On a shared VM or server, loopback is shared by every local account. Any other user on the host can reach the unauthenticated session API (raw prompts and completions) and the forward proxy (your credentials) without going through the tunnel. Please add a line to "The rule" saying the model assumes a host you are the only user of, or at least one you trust every account on. The same point you already make for shared OpenShift projects applies here.
| loginctl enable-linger "$USER" # keep it running after you log out | ||
| ``` | ||
|
|
||
| `agentop service` can manage the same unit if you install agentop on the server. In a |
There was a problem hiding this comment.
suggestion: agentop service install doesn't adopt the unit above. It writes its own unit to the same path (~/.config/systemd/user/cortex.service) with ExecStart=<abs binary> --config <cfg> and its own restart policy (cmd_service_platform.go), so it replaces the hand-written file. Maybe reword this as "or skip the hand-written unit: agentop service install writes and supervises an equivalent one". That also points readers to the hardened unit, with quoted absolute paths and restart backoff.
| Description=Cortex | ||
|
|
||
| [Service] | ||
| ExecStart=%h/cortex --local |
There was a problem hiding this comment.
nit: install.sh installs into ~/.local/bin (BIN_DIR in scripts/install.sh), so a reader who used the installer has no ~/cortex. %h/.local/bin/cortex would work out of the box, or add a comment saying to adjust the path.
…rvice note Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Hai Huang <huang195@gmail.com>
github-project-automation
Bot
moved this from New/ToDo
to Done
in Rossoctl Issue Prioritization
Summary
docs/remote.md— running the laptop-style Cortex on a remote machine (VM, server,pod) and connecting
agentopto it securely. Plus a docs-index row and a root-READMElink.
The design in one line
Cortex never learns it is remote: every listener stays loopback-bound and
unauthenticated, and an encrypted tunnel (
ssh -L,kubectl port-forward,oc port-forwardwith one project per user) carries loopback across the network — yourSSH key or cluster identity is the auth. Zero code change:
agentop observe --endpoint, the picker, andagentop service's Linux systemd path already existed.Verified end to end (Lima VM, Ubuntu 24.04 arm64)
cortex --localas a systemd user unit with linger; all ports on loopback.ssh -L,agentop observe --endpointrendering live remotesessions in the TUI.
DELETE /v1/sessionsallowed through the tunnel (loopbackHostpasses thebrowser guards) — cleared the store and the on-disk archive.
HTTPS_PROXYat the tunnelled forward proxy, HTTPS throughthe remote TLS bridge with the copied CA, session recorded and visible.
agentop exec --cortex-stats-urlagainst the remote stats port fetches the remoteconfig but prints the server's proxy address and CA path — documented as a
set-it-by-hand caveat rather than fixed.
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com