Getting Started with Grass in 5 Minutes

This guide walks you through installing the Grass CLI, connecting the Grass mobile app, and starting your first live agent session — all in under 5 minutes. By the end, you will have Claude Code or OpenCode running on your machine and streaming output to your phone, with agent approval gates surfacing as native modals.

TL;DR

• Install the Grass CLI with npm install -g @grass-ai/ide (Node.js 18+ required)
• Run grass start in your project directory to spin up the server and generate a QR code
• Scan the QR code with the Grass mobile app (iOS App Store or Android PWA)
• Select your repo, pick your agent, start a session, and send a prompt
• The whole process takes under 5 minutes if Claude Code is already installed
• Once connected, you have full mobile coding agent access — live output, approval gates, diffs, and bidirectional chat

Prerequisites

• Node.js 18 or higher — check with node --version. Install from nodejs.org if needed.
• Claude Code installed and authenticated — install with npm install -g @anthropic-ai/claude-code and run claude once to complete authentication. See the Claude Code getting started guide for details. Alternatively, OpenCode can be used instead.
• The Grass mobile app — download from the iOS App Store (search for Grass), or visit the Grass website on Android to install the PWA.
• A project directory — any git repository or folder you want the agent to work in.
• Same WiFi network — your phone and machine need to be on the same local network for the default setup. For remote access, see the Tailscale section below.

How does Grass connect your phone to a running agent?

Grass has two components: a CLI server that runs on your machine and a mobile app that connects to it.

Your phone (Grass app)
       |
       | HTTP + SSE over local WiFi
       |
Your machine (grass start)
       |
       | Agent SDK
       |
Claude Code / OpenCode process

When you run grass start, it spins up an HTTP server on a port in the range 32100-32199 and generates a QR code encoding that server's local IP and port. The Grass app scans the QR code, connects to the server over your local network, and subscribes to the agent's event stream via Server-Sent Events (SSE). Agent output streams to your phone in real time. Permission requests surface as modals. Your approvals are sent back to the agent via REST calls.

Nothing leaves your local network except the agent's own API calls to Anthropic. There is no cloud relay, no account required on the server side.

What does the Grass setup involve?

Setup has five steps: install the CLI, run grass start in your project directory, scan the QR code with the mobile app, start a Claude Code session, and optionally configure Tailscale for remote access. Steps 1–4 take under 5 minutes. Step 5 is optional and only needed if you want to connect from outside your local network.

Step 1: Install the Grass CLI

npm install -g @grass-ai/ide

This installs the grass command globally. Verify the installation:

grass --version

You should see a version number printed. If you see command not found, your npm global bin directory may not be in your PATH — run npm bin -g to find the path and add it to your shell profile.

Common issue: If you get a permissions error on macOS or Linux, avoid using sudo. Instead, configure npm to use a user-writable directory for global installs. See npm's guide on fixing permissions.

Step 2: Navigate to your project and start Grass

cd ~/projects/my-repo
grass start

Grass auto-selects an available port from 32100-32199 and prints output like:

Starting grass server...
  workspace: /Users/you/projects/my-repo
  port: 32100
  available agents: claude-code, opencode

  Local Network  http://192.168.1.42:32100

  [QR code]

  Scan to open on your phone

Leave this terminal running. The Grass server stays alive as long as this process is running.

What to expect: The QR code encodes a plain http:// URL — your phone's camera or QR scanner does not need any special handling.

Common issue: If port 32100 is already in use, Grass will try the next port up automatically. If the entire range 32100-32199 is occupied, you will see an error — use -p to specify a different port: grass start -p 8080.

Step 3: Connect the Grass mobile app

Open the Grass app on your phone. On the home screen, tap Scan QR Code. Point your camera at the QR code in the terminal. The server connection is added to your list immediately.

You should see the server appear with a green status indicator, and the workspace path printed below the server name.

Common issue: If the connection fails immediately after scanning, your phone and machine are likely on different networks (e.g. your machine is on Ethernet, your phone is on WiFi, and they are on different subnets). Confirm both are on the same network. For cross-network access, see Step 5.

Step 4: Start a Claude Code session

In the Grass app:

1. Tap the server you just connected.
2. You will see a list of repositories — these are the subdirectories of the workspace where you ran grass start. Tap your repository.
3. An agent picker appears inline. Select Claude Code (or OpenCode if you have it installed).
4. You will see any existing sessions for this repo and agent. Tap the + button to start a new session.
5. Type your first prompt in the chat input and send it.

Claude Code starts immediately — it is running as an AI coding agent on your machine, reading your files and responding to your prompt. You will see output streaming into the chat view: status indicators as the agent thinks, tool use events as it reads files, and assistant messages as it responds.

What success looks like: Within a few seconds of sending your prompt, you should see activity in the chat view — the agent reading files, thinking, or beginning to write a response.

Common issue: If the agent picker shows no agents, Claude Code is either not installed or not authenticated. Run claude in the terminal to check. If it prompts for authentication, complete the flow and try again.

Step 5: Set up remote access with Tailscale (optional)

The default setup works over local WiFi. If you want to connect from a different network — checking on an overnight run from outside your home, or monitoring an agent from your commute — use Tailscale.

Install Tailscale on both your machine and phone, then start Grass with:

grass start --network tailscale

Grass will detect your Tailscale IP and encode it in the QR code instead of your LAN IP. As long as both devices are on the same Tailscale network, the connection works from anywhere.

Alternatively, for a machine with a public IP:

grass start --network remote-ip

This fetches your public IP from api.ipify.org and uses it in the QR code. Note that Grass has no authentication — anyone who can reach the port can interact with your sessions. Restrict port access via firewall rules if using public IP.

How do I know Grass is working correctly?

A working setup looks like this:

• The Grass app shows your server with a green status indicator
• Tapping the server shows your repository list
• Starting a session and sending a prompt produces streaming output in the chat view within a few seconds
• If you trigger an action that requires approval (e.g. ask the agent to write a file), a permission modal appears on your phone

To test the permission modal specifically: start a session and ask the agent to create a new file. Claude Code will pause and request approval before writing. You should see the modal appear with a diff preview of the proposed file content.

Troubleshooting

Problem: QR code scans successfully but the app immediately shows a connection error. Fix: Your phone and machine are on different networks or subnets. Check both are on the same WiFi. If your machine is on Ethernet, try switching it to WiFi temporarily, or use grass start --network tailscale.

Problem: grass start prints a URL but no QR code appears. Fix: Your terminal may not support QR code rendering. The URL printed above the QR code is the same information — you can type it manually in the Grass app by tapping Add server manually instead of scanning.

Problem: Agent picker shows Claude Code but starting a session immediately errors. Fix: Run claude --version in the terminal to confirm Claude Code is installed and authenticated. If authentication has expired, run claude to re-authenticate.

Problem: Permission modals are not appearing when the agent hits an approval gate. Fix: Confirm the Grass app is in the foreground. Grass surfaces permission modals as in-app overlays — if the app is backgrounded, they queue and appear when you reopen the app. The agent waits indefinitely, so nothing is lost.

Problem: Multiple grass start instances are running and the app is showing the wrong session. Fix: Each grass start instance has its own QR code and port. Check the server list in the Grass app and confirm you are connected to the right server by comparing the workspace path shown under the server name.

Next steps

Monitor a long-running coding agent overnight — Once Grass is set up, this covers the overnight monitoring workflow in detail: how live output streaming works, how to handle approval gates remotely, and how sessions recover from disconnects.

Connect Grass to Daytona — Run your agent on a cloud workspace instead of your laptop. Grass connects to Daytona workspaces the same way it connects to local machines — this guide covers the differences and the Tailscale setup for remote access.

How to connect Grass to Claude Code — A deeper look at the Claude Code integration: how sessions are managed, how transcripts work, how to resume sessions, and how the permission system operates in detail.

Frequently asked questions

Does Grass work on Android?

Yes. The Grass native app is iOS-only (App Store), but Android users can install the PWA. Visit the Grass website on your Android device and follow the browser prompt to add it to your home screen. The PWA has the same core functionality as the iOS app — live output streaming, permission modals, diff viewer, and multi-server support.

Do I need a Grass account to use it?

No account is required on the server side. The Grass CLI (grass start) runs entirely on your machine with no sign-in. The mobile app does not require an account to connect to a local server. Grass is free for local use — download the app, install the CLI, and start a session.

Can I use Grass with OpenCode instead of Claude Code?

Yes. Grass supports both Claude Code and OpenCode. When you tap a repository in the app, an inline agent picker lets you choose which agent to use for the session. OpenCode must be installed on your machine — Grass detects it at startup and lists it as an available agent alongside Claude Code.

What if the QR code scan fails or the URL doesn't connect?

The most common cause is a network mismatch — your phone and machine are on different networks or subnets. Confirm both are on the same WiFi network. If you cannot put them on the same network, use grass start --network tailscale with Tailscale installed on both devices. As a fallback, tap Add server manually in the Grass app and type the URL printed above the QR code directly.

Can I run Grass on a remote server or cloud VM?

Yes. Install the Grass CLI on the remote machine, run grass start --network tailscale (recommended) or grass start --network remote-ip, and scan the QR code it generates. The connection works identically to the local case. This is the basis for the Daytona integration — see Connect Grass to Daytona for a full walkthrough.

How do I keep Grass running if I close the terminal?

Run grass start inside a terminal multiplexer like tmux or screen. This keeps the process alive after the terminal session ends or the SSH connection drops. For example: tmux new-session -d -s grass 'grass start'. The agent sessions running inside Grass also benefit from this — they survive terminal disconnects independently of the Grass server.