Pencil / docs
Guide3 min readUsing Pencil

Pencil Gateway

Install, pair, and run Pencil-assigned work on your computer.

Pencil Gateway runs Pencil-assigned chats and tasks through your local Claude Code installation. Choose it when you want work to execute on a machine you control. Your Claude credentials stay local.

If you only want an external client to read or update Pencil through a hosted connection, go directly to Pencil MCP Server. Hosted MCP needs no gateway installation.

Install

For local task execution, install Node.js 20 or newer, npm, and a working, signed-in claude CLI on your PATH. Then install the gateway:

npm install -g @pencilink/gateway

The macOS and Linux double-click installers also install, pair, and start a user-level service. If you have an installer archive, extract it and open Install Pencil Gateway.command on macOS or Install Pencil Gateway.desktop on Linux. Linux may require Allow Launching. Neither installer needs sudo.

Pair and run

  1. In Pencil, open Settings → Agent runtime, choose Run on my computer, and select Generate pair code. Codes expire after 15 minutes and can be used once.
  2. Run pencil-gateway pair and paste the code when prompted.
  3. Run pencil-gateway doctor to check the local setup, then pencil-gateway start to start picking up eligible work.

Leave the process running; Ctrl+C stops it. By default, the gateway runs up to three independent dispatches while keeping each task or chat thread serialized. Reduce local load with:

pencil-gateway start --max-concurrency 1

Pairing stores a device token in ~/.pencil/gateway.json with user-only permissions. Treat it like a private key. Revoke a lost or unused device in Pencil settings.

Self-hosted Pencil and multiple accounts

Pair against your own Pencil host with:

pencil-gateway pair --mc-url https://pencil.example.com

The saved URL is reused by start, status, doctor, and paired mcp. You can also set PENCIL_MC_URL before pairing.

Use named profiles to run separate accounts:

pencil-gateway pair --account work
pencil-gateway start --account work
pencil-gateway list

Profiles live in ~/.pencil/gateway.<account>.json. Use the same --account flag for diagnostics and services, and run one daemon per profile.

Run at sign-in

After a command-line installation and pairing:

pencil-gateway service install
pencil-gateway service status

This installs a user-level launchd service on macOS or systemd service on Linux. It starts at sign-in and restarts after unexpected failures. Double-click installers configure this automatically.

For global npm updates, run npm install -g @pencilink/gateway@latest, then pencil-gateway service install again. The double-click installer can enable managed automatic updates.

pencil-gateway service uninstall removes startup definitions while preserving pairing, work files, and logs. pencil-gateway unpair also removes the local pairing config.

Troubleshooting

SymptomWhat to check
No paired gatewayRun pencil-gateway status with the matching --account.
Tasks or chats do not startCheck Run on my computer, the running daemon, and pencil-gateway doctor.
Expired Claude sessionSign in to Claude Code as the same OS user, restart the gateway, and select Resend in Pencil.
Device token returns 401Revoke the stale device in Pencil settings and pair again.
Service will not runCheck pencil-gateway service status; reinstall the service if Node or Claude moved.

On macOS, inspect ~/.pencil/logs/gateway*.log. On Linux, use journalctl --user -u pencil-gateway.service for the default profile.

What to try next

Connect a client using Pencil MCP Server. The gateway's mcp command provides stdio access separately from the task daemon.