Solsquare
Dashboard

Overview

Solsquare lets you drive a coding agent on your own machine from anywhere, and privately view your localhost over the internet.

How it fits together

A small CLI (the connector) runs on your machine and dials an outbound WebSocket to the platform. Nothing on your side needs an open inbound port, so it works behind NAT and strict firewalls.

  • Chat — you type instructions in the web app; the connector runs them through your local agent CLI and streams output back.
  • Tunnel — the connector exposes a chosen local port at an owner-only URL like dev-you.t.solsquare.app.
Your agent runs on your machine with your own tools and keys. Solsquare never sees your code or your API keys.

Core concepts

  • Project — a workspace with its own chat, tunnels, and connector.
  • Access token — an account-level API key you put in a project's .env.
  • Slug — a friendly subdomain per tunnel: <name>-<username>.t.solsquare.app.

Quickstart

Two commands. No tokens to copy, no .env to write.

1. Install the CLI

npm i -g @solsquare/tunnel

2. Log in

tunnel login

Your browser opens with a short code. Approve it, and the CLI generates its own access token and saves it to ~/.solsquare/config.json. You only do this once per machine.

3. Connect

From the folder you want to drive:

cd ~/my-project
tunnel init # once per folder: teach the agent this project
tunnel connect
# add --expose 3000 to also tunnel a local port

If the folder has no project yet, one is created named after it. The project flips to online — now chat with your agent and open your tunnel URL from any device.

The folder you run tunnel connect in is the agent's knowledge base. tunnel init writes a CLAUDE.md there so every chat message starts oriented — see Project context.
On a headless box or over SSH, use tunnel login --no-browser and open the printed URL on your phone or laptop.

Install the CLI

The tunnel CLI is published on npm.

npm i -g @solsquare/tunnel
tunnel --help

Requirements

  • Node.js 20+
  • A coding-agent CLI on your machine (default: claude). Any agent works.

Commands

  • tunnel login — sign in via the browser; mints and saves an access token.
  • tunnel connect — connect this folder (creates/reuses a project).
  • tunnel expose <port> — connect and tunnel a local port.
  • tunnel projects — list your projects and whether each is online.
  • tunnel whoami — show the signed-in account.
  • tunnel logout — revoke this machine's token and sign out.

Configuration

After tunnel login there's nothing to configure — credentials live in ~/.solsquare/config.json (readable only by you). To override, the CLI still reads .env from the current directory, and real environment variables win over both:

TUNNEL_TOKEN=...            # skip `tunnel login` (CI, containers)
TUNNEL_URL=wss://app.solsquare.app/connect
AGENT_CMD=claude -p {prompt}   # optional; the agent to run
PROJECT_DIR=.                # optional; where the agent runs

Connecting a project

One connector per project, dialed out from your machine.

cd ~/my-project
tunnel connect --expose 3000

Which project?

With no flags, tunnel connect picks the project in this order:

  • --project <name|id>, if you pass one — an unknown name creates that project.
  • the project this directory connected to last time;
  • a project matching the folder's name — created if it doesn't exist yet.

Flags

  • --project <name|id> — the project to attach to.
  • --expose <ports> — comma-separated local ports to tunnel.
  • --resume <session-id> — continue a specific saved agent conversation.
  • --token, --server, --dir — override the saved login / env values.
The connector must stay running (a terminal, a background process, or an always-on box). Restart it and it reconnects automatically.

Project context

The folder you connect from is the agent's knowledge base.

tunnel connect runs your agent in the directory you invoke it from, so that folder is what it can see. Every chat message spawns a fresh agent process — that keeps each turn cheap and independent, but it also means that without a project file the agent starts cold and rediscovers your repo every single time.

tunnel init

Run it once per folder. It points your own agent at the project and has it write a CLAUDE.md: what the project is, its layout, the commands that matter, the conventions, and the non-obvious gotchas. Agents load that file automatically at startup, so every chat message begins oriented.

cd ~/another-project
tunnel init
tunnel connect

tunnel connect tells you when a folder doesn't have one yet. Nothing is overwritten: if a context file already exists, init leaves it alone unless you pass --force.

Options

  • --file <name> — write a different file (CLAUDE.md by default; AGENTS.md is also recognised).
  • --force — regenerate even if one exists.
  • --dir <path> — target another folder.

Context vs. memory

These are two different things, and you want both:

  • Project context — CLAUDE.md, per folder. Survives forever, applies to every message.
  • Conversation memory — AGENT_CONTINUE_CMD (claude --continue by default). Carries context between your chat messages.
Because the file is written by your agent, it works with whatever AGENT_CMD points at — the platform stays agent-agnostic.

Chat & your agent

Type instructions; your machine's agent runs them and streams back.

Each message runs your configured AGENT_CMD in PROJECT_DIR. Follow-up messages continue the same conversation, so context carries over. Hit New chat to start fresh.

The prompt is passed to the agent as a single argument — never shell-interpolated.

Away from keyboard

Because the connector holds the link open, you can walk away and keep driving the agent from your phone. Great for kicking off a change while you're out.

Tunnels

Expose a local port at an owner-only URL.

Register a port in the dashboard (or with --expose), then open the generated URL:

https://<name>-<username>.t.solsquare.app

Each tunnel gets its own subdomain, so apps load at the root and their absolute asset paths (like /_next/…) resolve correctly.

Access is owner-only

Every request checks a valid session and that the tunnel belongs to you. Opened logged-out or by anyone else, it's refused.

Access tokens

Account-level API keys — one works across all your projects.

tunnel login creates one for you automatically, named after your machine, and saves it to ~/.solsquare/config.json. Most people never need to touch this page.

Creating one by hand

For CI, containers, or a shared box, generate a token on the Access page. It's shown once and stored only as a hash. Pass it as TUNNEL_TOKEN and the CLI will skip the login step.

Revoking

Revoke a token anytime from the Access page — any connector using it disconnects immediately and it can't reconnect. tunnel logout revokes that machine's own token.

Resuming a session

Point the app chat at a specific saved agent conversation.

tunnel connect --project <id> --resume <session-id>

Every message then continues that exact conversation, so the app chat picks up where your desktop session left off. Best used when you drive from one place at a time.

Self-hosting

The platform is a single Node process + SQLite — trivial to run yourself.

Point the CLI at your own server by changing TUNNEL_URL:

TUNNEL_URL=wss://your-host/connect

Bring your own agent, your own machine, your own server. See the repository for deployment configs (Docker, Fly.io, a Caddy + systemd VM).

FAQ

Does Solsquare see my code or keys?

No. The agent runs on your machine with your own tools and API keys. Solsquare only relays chat text and proxies tunnel HTTP.

Does it work behind a corporate firewall?

Yes — the connector dials outbound over WSS, so no inbound ports are needed.

Which agents are supported?

Any CLI agent. The default is claude -p, but you can set AGENT_CMD to anything.

What's free vs Pro?

Free includes 1 project with all features. Pro ($4.99/mo) unlocks unlimited projects.