Support & Setup Guide

Getting Started

For a detailed walkthrough including how the rules system works, see the setup guide.

1. Install the App

Download Greenlight from the App Store or Google Play and open it. The app will automatically generate a unique device ID and connect to the relay server.

2. Copy Your Device ID

Go to the About tab in the app and tap your Device ID to copy it to the clipboard. You'll need this for the next steps.

3. Install greenlight-cli

Run the install script (requires Go 1.19+):

curl -sSL https://aigreenlight.app/install.sh | bash

This clones the repo, builds from source, and installs the binary to /usr/local/bin.

Alternatively, unsigned pre-built binaries are available from GitHub releases (see that page for macOS Gatekeeper instructions).

Register your device ID (you only need to do this once):

greenlight register YOUR_DEVICE_ID

You can also pass --device-id as a flag or set the GREENLIGHT_DEVICE_ID environment variable.

4. Set Your Default Agent

greenlight agent claude

Supported values: claude, copilot, cursor, codex, gemini, pi. You only need to do this once.

5. Launch

cd your-project
greenlight

greenlight-cli launches your agent in yolo mode so it never blocks on a terminal prompt. Greenlight's libhook permission engine intercepts all reads, writes, network IO, and shell commands — forwarding them to your phone for approval. On first launch, you'll see an enrollment prompt on your phone — tap Allow. After that, new sessions connect automatically.

To resume a previous session:

greenlight --resume SESSION_ID

6. Test It

Ask your agent to do something that requires permission, like writing a file. You should see a request appear in the app.

greenlight-cli Options

Option	Description	Default
--device-id ID	Your device ID from the app	Config file or env var
--project NAME	Project name shown in the app. Rules are scoped per-project.	Current directory name
--resume SESSION_ID	Resume a previous session instead of starting a new one	—

Configuration priority: command-line flag > environment variable (GREENLIGHT_DEVICE_ID) > config file (~/.greenlight/config).

Using the App

Permission Decisions

Each request can be responded to with four actions:

• Always Allow — Approves and creates a rule so future matching requests are auto-approved.
• Allow — Approves this one request.
• Deny — Denies this one request.
• Deny & Stop — Denies and sends a halt signal to stop the agent entirely.

How Rules Work

Tapping "Always Allow" generates a pattern that auto-approves future matching commands without interrupting you.

Patterns are subcommand-aware. The system knows that git push and git status are different operations:

• go build ./cmd/foo → pattern Bash(go build **) — matches any go build
• git push origin main → pattern Bash(git push **) — matches any git push, but not git reset
• aws s3 cp file.txt s3://bucket/ → pattern Bash(aws s3 cp **) — three-word prefix for AWS/GCloud

Commands like rm, sudo, kill, and chmod use exact matching. Granting rm -rf /tmp/coverage creates a rule that matches only that exact string — not rm -rf /home.

For compound commands like git add . && git commit -m "msg" && git push, the system splits into segments and generates a separate pattern for each. All segments must have matching rules for auto-approval. Each segment is color-coded by risk (green/orange/red) and segments already covered by rules show a checkmark overlay.

For Read, Write, and Edit tools, patterns match on the directory (e.g., Edit(/home/user/project/src/**)).

Managing Rules

The Grants tab shows all your "Always Allow" rules grouped by project. Swipe left on any rule to delete it.

Talk to Your Agent from Your Phone

The Activity tab shows an input bar at the bottom. Anything you type is sent directly to your agent session as if you typed it at the terminal. Use this to answer prompts, provide additional context, or nudge your agent in a different direction.

Greenlight Pro adds push notifications, voice input, Pull the Plug, and temporary grants.

Notifications

Greenlight uses Time Sensitive notifications that can break through Focus modes. Make sure notifications are enabled in Settings → Greenlight → Notifications and that Time Sensitive notifications are allowed in your Focus mode settings.

Secrets

Greenlight lets your agents use API keys, tokens, and OAuth credentials without ever seeing the values. Secrets are encrypted on your phone using a public key whose private half never leaves your computer — the relay server stores only ciphertext.

1. Initialize a key pair

On the machine where your agents run:

greenlight secrets init

This generates a public/private key pair under ~/.greenlight/. The public key is uploaded to the relay; the private key stays local.

2. Add secrets from the app

Open the Secrets tab in the Greenlight app. You can either:

• Add a custom secret — paste any value (API key, token, password) and give it a name.
• OAuth with a provider — connect Google, GitHub, Linear, Slack, or Notion in one tap. Greenlight handles the OAuth flow and stores the resulting access token.
• Custom OAuth — connect any other provider by filling in the OAuth form (authorization URL, token URL, client ID/secret, scopes). Useful for self-hosted services or providers not in the built-in list.

Secrets are encrypted on your phone with your machine's public key before being sent to the relay. Only your computer can decrypt them.

3. Use secrets from your agent

Agents see what's available with:

greenlight secrets list

To run a command with a secret injected as an environment variable:

greenlight run -e GITHUB_TOKEN -- gh pr list

Pass -e multiple times to inject several secrets. greenlight run is the only path to a secret value — the agent never reads it directly.

Run greenlight run --help for more details and example usage.

How leaks are prevented

• Output scrubbing — stdout and stderr from greenlight run are scanned and any occurrence of a secret value is replaced with *** before the agent sees it. Running greenlight run -e foo -- printenv foo prints ***.
• Permission-gated — every greenlight run invocation triggers a permission request on your phone, just like any other command. You can Always Allow safe read-only patterns (e.g. greenlight run -e GITHUB_TOKEN -- gh pr list) and keep destructive ones one-tap.
• No reuse — the secret only exists in the environment of the child process. The agent can't capture it for later use without going back through greenlight run — which prompts you again.

Managing secrets

The app's Secrets tab lists everything you've added. Swipe to delete — the next greenlight secrets list won't show the secret. Expired OAuth access tokens are refreshed automatically on use when the provider issued a refresh token, so you don't need to reconnect.

Troubleshooting

Not receiving requests

• Check the About tab — the status should show "Connected" with a green dot.
• Verify your device ID in ~/.greenlight/config matches the one shown in the app.
• Make sure you launched your agent with greenlight.

Session not appearing on phone

• Verify the device ID in your ~/.greenlight/config matches the one in the app's About tab.
• Check the phone's connection status — the About tab should show a green "Connected" dot.
• The session should appear immediately when you run greenlight. If it doesn't, check the greenlight log file for errors.

Not receiving push notifications

• Check that notifications are enabled: Settings → Greenlight → Notifications.
• If using a Focus mode, make sure Greenlight is in the allowed apps list or Time Sensitive notifications are enabled.
• Push notifications are sent when the app is backgrounded. If the app is in the foreground, requests arrive directly via WebSocket.

Connection drops when computer is idle

If your agent's connection drops after a period of inactivity, your computer is likely sleeping. Adjust your power settings so it stays awake while greenlight is running:

• macOS — System Settings → Lock Screen (or Battery on laptops), and set "Turn display off on power adapter when inactive" to Never, or enable "Prevent automatic sleeping on power adapter when the display is off". Alternatively, run caffeinate in a terminal to keep the system awake temporarily.
• Ubuntu — Settings → Power, and set "Automatic Suspend" to Off and "Screen Blank" to Never. On a server or headless system, run systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target.

"daemon started but socket not ready"

Usually caused by a stale daemon owned by root holding the socket. This can happen if sudo greenlight update failed partway through, leaving a root-owned daemon running. Check with:

ls -l /tmp/greenlight-daemon.sock ~/.greenlight/daemon.pid
ps -o user,pid,command -p $(cat ~/.greenlight/daemon.pid)

If the socket or pid file is owned by root, kill the stale daemon and remove the leftover files, then restart:

sudo kill $(cat ~/.greenlight/daemon.pid)
sudo rm /tmp/greenlight-daemon.sock ~/.greenlight/daemon.pid
greenlight

Contact

For bug reports, feature requests, or any questions, email support@aigreenlight.app.