single static Go binary · MIT

Beam a file onto a remote box.
Print the path. Let the agent read it.

clipbeam is a single static Go binary that pushes a file, screenshot, or clipboard from your laptop onto a remote box's disk — over your existing SSH or Tailscale — and prints the absolute path, so a coding agent on that box can just read it.

↓ Install clipbeam See the flow
push-only no daemon required rides your SSH
the gap

There is no shared clipboard across the SSH boundary.

You drive a coding agent on a headless box, but the one thing it can ingest is a real file on its own disk. Getting bytes there is easy; landing a clean, machine-readable path is not.

  • 01

    You run a coding agent on a headless Linux box and SSH in to drive it — but you can't paste an image into that remote TUI. The terminal reads your local clipboard; there is no shared pasteboard across the SSH boundary.

  • 02

    The only thing a remote agent can ingest is a real file on the box's disk it can read by absolute path. scp and rsync get the bytes there, but then you're hand-juggling paths and there's no inbox.

  • 03

    Pastebins and gists leak your screenshot to a third party — and still don't land a path on the box.

  • 04

    Most file-movers were built for humans. Nothing emits stable JSON, a deterministic exit-code table, or a machine-readable surface an agent can drive with no guessing.

how it works

Pair once. Beam. Read the path.

Three commands. The bytes ride the connection you already have, and the agent gets a real file by absolute path — nothing else to wire up.

  1. STEP 01

    Bootstrap a box once over SSH

    Rides the SSH connection you already have: detects the remote arch, streams the matching static binary, verifies the host key against known_hosts, and pairs. No new account, no open ports, no config editing.

    $ clipbeam setup root@my-box
  2. STEP 02

    Beam a file or screenshot

    Lands the file on the box's disk and prints the REMOTE absolute path on stdout. Use clipbeam shot to capture the screen and beam the PNG in one step.

    $ clipbeam send screenshot.png my-box
  3. STEP 03

    Your agent reads the path

    clipbeam last prints the most-recently-received absolute path with no trailing newline — drop it straight into a prompt. The agent reads a real file; nothing else to wire up.

    box$ claude "describe the image at $(clipbeam last)"
install

One file. No runtime deps.

A single static binary. Pick any path — all three work and stay current.

homebrew · recommended
brew install vybzai/tap/clipbeam
curl
curl -fsSL https://raw.githubusercontent.com/vybzai/clipbeam-cli/main/install.sh | sh
go toolchain
go install github.com/vybzai/clipbeam-cli/cmd/clipbeam@latest
Hand it to your agent

Copy a ready-made onboarding prompt that teaches a coding agent exactly how to use clipbeam — every core verb, the install lines, and the clipbeam schema pointer. Paste it into the agent and it knows the tool. One step in: clipbeam install-skill writes a clipbeam skill into ~/.claude/skills and ~/.codex/skills, so the agent knows it in every future session too.

what it does

Built to move bytes the way an agent needs them.

  • send · shot

    Screenshots & files land on the box's disk; clipbeam prints the remote absolute path. clipbeam shot captures the screen and beams the PNG in one step.

  • push

    Clipboard, beamed. Send the current local clipboard contents straight to the box on the clipboard channel.

  • msg · recv

    Agent-to-agent channel: a private inbox drained by clipbeam recv (FIFO long-poll). msg beams text with --reply-to for correlation.

  • push-only

    Push-only by design — nothing leaves a machine unless you act. There is no pull, no fetch, no silent sync.

  • ssh · tailscale

    Rides the SSH tunnel you already have; host keys verified against known_hosts. Tailscale is optional for always-on. --transport auto prefers Tailscale when the box answers /health, else falls back to SSH — same command.

  • clipbeam schema

    Self-describing surface: every verb, flag, JSON shape, and exit code, machine-readable. Agents read the schema, not the docs.

built for agents

A machine-readable surface, end to end.

Every verb takes --json, returns a stable versioned object, and exits on a deterministic code. No screen-scraping, no guessing.

$ clipbeam send screenshot.png box --json 
{
  "schema": "clipbeam.v1",
  "ok": true,
  "sentItems": 1,
  "remotePath": "/home/user/.clipbeam/in/screenshot.png"
}
  • --json on every verb

    Add --json (or set CLIPBEAM_JSON) to any command for a stable, versioned object.

  • Deterministic exit codes

    Scripts branch with confidence — the exit code is part of the contract, not an afterthought.

  • clipbeam schema

    Runtime self-description: every verb, flag, JSON shape, and exit code. The authoritative surface.

Agents branch on the payload (path:null / item:null), not the exit code.
ExitMeaning
0success
1generic failure
2usage / bad args
3nothing available
4unauthorized
5forbidden
6peer offline / transport unreachable / host-key unknown or changed
7payload too large
8config / identity error
9remote / peer I/O error
security

Rides your tunnel. Leaks nothing.

SSH is the default transport, so encryption, authentication, and NAT traversal come for free — with no new account and no open ports.

  • Push-only by design

    Nothing leaves a machine unless you act. There is no pull and no silent sync.

  • Rides your existing SSH

    Host keys verified against known_hosts (strict; no --insecure). No new account. Tailscale optional, gated by exact peer IP plus a constant-time token.

  • Secrets stay local

    Stored in the macOS Keychain or a 0600 token file on Linux. Logs redact the token and all X-ClipBeam-* headers.

  • 50 MB payload cap

    Payloads are capped at 50 MB; anything larger fails fast with exit code 7. MIT licensed.

Beam it. Print the path.

homebrew · recommended
brew install vybzai/tap/clipbeam
View on GitHub ↗
Copied to clipboard