Run Gemini CLI on a remote server

Install Gemini CLI#

On your computer, create a VM and connect. Pick any free name; if you've already clicked Deploy or have a VM, skip the first command and use its name:

ssh exe.dev new --name=my-gemini-cli
ssh my-gemini-cli.exe.xyz

On the VM, install Node.js 24 from NodeSource (Gemini CLI needs Node.js 20 or newer) and Gemini CLI from npm:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g @google/gemini-cli@latest
gemini --version

It prints a version such as 0.66.0.

Connect it to Gemini#

Open this link on your computer to add a Gemini integration attached to the VM. Keep the name gemini, paste your Gemini API key, and save:

https://exe.dev/integrations/add?service=gemini&attach=vm:my-gemini-cli

The VM can now reach the Gemini API at https://gemini.int.exe.xyz, with your key added by exe.dev. On the VM, check it:

curl -fsS https://gemini.int.exe.xyz/v1beta/models | jq -r '.models[0].name'

It prints a model name, such as models/gemini-2.5-flash. A 403 saying integration not found or not attached to this VM means the integration has another name or isn't attached to this VM yet.

Point Gemini CLI at that address. Gemini CLI insists on an API key value, so it gets a placeholder; the integration replaces it with yours:

mkdir -p ~/.gemini
cat > ~/.gemini/.env <<'EOF'
GOOGLE_GEMINI_BASE_URL=https://gemini.int.exe.xyz
GEMINI_API_KEY=added-by-exe-dev
EOF
chmod 600 ~/.gemini/.env
cat > ~/.gemini/settings.json <<'EOF'
{
  "security": { "auth": { "selectedType": "gemini-api-key" } }
}
EOF

Make a project folder, a Git repository so you can review and undo what Gemini changes, and ask it something without opening the interactive screen:

git init ~/project
cd ~/project
gemini --skip-trust -m flash-lite -p "Reply with exactly: OK"

It prints OK. --skip-trust answers the folder-trust question you'll see in the next step, for this run only, and -m flash-lite picks Google's smallest current model, which free keys can use too.

Start coding#

Open a tmux session in the project:

tmux new -A -s gemini -c ~/project

Inside that session, start Gemini CLI:

gemini

The first time, it asks whether you trust the files in this folder. Choose Trust folder: Gemini CLI only reads ~/.gemini/.env and project settings in folders you trust. Then give it a small task. For example:

Build a tiny website for a lighthouse keeper who reviews passing ships.

Note

Gemini CLI's default model setting, Auto, sends harder prompts to a Pro model. Keys on Google's free tier can't use Pro, so Gemini CLI retries and then falls back to Flash, which can take minutes. With a free key, start it as gemini -m flash (or -m flash-lite), or pick a model with /model.

Gemini CLI asks before it edits a file or runs a command. Press Shift+Tab to let it accept edits on its own; type /help for the rest.

Take a break#

Press Ctrl-b, then d to detach. Gemini CLI keeps working on the VM when you disconnect. On your computer, use this command to hop back in:

ssh -t my-gemini-cli.exe.xyz 'tmux new -A -s gemini -c ~/project'

A VM restart ends the running session, but not your saved work. Reconnect and run gemini --resume latest from your project's folder on the VM to pick up its last conversation.

Tip

Before a big unattended job, take a copy of the VM with ssh exe.dev cp my-gemini-cli my-gemini-cli-backup on your computer. If the job goes sideways, carry on from the copy.

Run it headless#

gemini -p runs one prompt and exits, which makes Gemini CLI a tool for scripts, cron jobs and other agents. It reads anything piped into it:

cd ~/project
git diff | gemini -p "Write a commit message for these changes"

Without a screen to ask on, Gemini CLI refuses anything that needs your approval. Say what it may do instead: --approval-mode=auto_edit lets it edit files, and --approval-mode=yolo lets it run any command too, which is what a throwaway VM is for. -o json returns one JSON object with the answer in response:

gemini --approval-mode=auto_edit -o json \
  -p "Add a README.md that explains this project" | jq -r .response

A scheduled run is one cron line. Run crontab -e and add, for example, a nightly review at 06:00 UTC:

0 6 * * * cd ~/project && gemini --skip-trust -p "List the TODOs in this repo, most urgent first" >> ~/gemini-todos.log 2>&1

The exit code is 0 on success, 1 on an error, 42 for bad input and 53 when the run hits its turn limit. Google's headless mode reference has the stream-json event format.

Add MCP servers#

Gemini CLI loads MCP servers from ~/.gemini/settings.json, or from .gemini/settings.json in a project. gemini mcp add writes the entry for you: pass --scope user for every project, as its default is the current project only.

For example, connect exe.dev's MCP server so Gemini can create VMs of its own: to try something risky on a copy, or to host what it builds. It runs unattended here, so give it a token that can only touch VMs tagged agent and expires in 30 days rather than your whole account. On your computer:

ssh exe.dev ssh-key generate-api-key --label=gemini --tag=agent --exp=30d \
  '--cmds="help,whoami,ls,new,rm,ssh,cp,stat,comment,share show,share port"'

It prints a token that starts with exe1.. On the VM, add it to ~/.gemini/.env (replace exe1.… with the token) and register the server. The single quotes keep ${EXE_TOKEN} as written, so Gemini CLI reads the token from .env each time it starts instead of saving it in settings.json:

echo 'EXE_TOKEN=exe1.…' >> ~/.gemini/.env
gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer ${EXE_TOKEN}' exe https://exe.dev/mcp
cd ~/project && gemini mcp list

gemini mcp list shows exe as Connected. In Gemini CLI, /mcp lists each server's tools. Limit what the agent can touch explains the token's options.

A local server that runs as a command works the same way, without --transport: gemini mcp add --scope user <name> <command> [args...]. See Google's MCP guide for per-tool filters and OAuth servers.

Work on a GitHub repository#

The GitHub integration lets the VM clone and push a repository without a GitHub token on it. Connect your GitHub account on the Integrations page once, then, on your computer, add the repository (replace you/your-repo):

ssh exe.dev integrations add github --name your-repo \
  --repository you/your-repo --attach vm:my-gemini-cli

On the VM, clone it, tell Git who you are, and start Gemini CLI in it:

git clone https://github.int.exe.xyz/you/your-repo.git ~/your-repo
git config --global user.name "Your Name"
git config --global user.email you@example.com
tmux new -A -s your-repo -c ~/your-repo
gemini

Ask for a change on a branch, then let Gemini push it and open a pull request with the preinstalled gh, which goes through the same integration when GH_HOST points at it:

Fix the flaky date test on a new branch, commit it, push the branch, and open a pull request with GH_HOST=github.int.exe.xyz gh pr create.

Pushes show up as the exe.dev GitHub App; add --act-as-user to the integrations add command to push as yourself. Put project instructions for Gemini in a GEMINI.md at the top of the repository; it reads that file at the start of every session.

Other ways to sign in#

cat > ~/.gemini/.env <<'EOF'
GEMINI_API_KEY=paste-your-key-here
EOF
chmod 600 ~/.gemini/.env

cat > ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT=your-project-id
EOF
cat > ~/.gemini/settings.json <<'EOF'
{
  "security": { "auth": { "selectedType": "oauth-personal" } }
}
EOF

Troubleshooting#

• When using Gemini API, you must specify the GEMINI_API_KEY environment variable: Gemini CLI didn't read ~/.gemini/.env. It reads only the first .env it finds, starting in the current folder, so a project with its own .env hides yours. Copy the two lines into the project's .gemini/.env (and keep that out of Git), or run set -a; . ~/.gemini/.env; set +a before gemini. It also skips .env files in folders you haven't trusted; trust the folder, or pass --skip-trust to headless runs.
• Gemini CLI is not running in a trusted directory: a headless run in a new folder. Add --skip-trust, or open gemini there once and trust it.
• 403 and integration not found or not attached to this VM: the Gemini integration isn't attached to this VM, or isn't called gemini. Check on the Integrations page, and use its name in GOOGLE_GEMINI_BASE_URL.
• 429 and You have exhausted your daily quota on this model: the key's project hit Google's limit for that model; free-tier keys get little or none (limit: 0 means none). Switch model with /model or -m flash-lite, or link billing to the project in Google AI Studio.
• 503 and This model is currently experiencing high demand: Google is busy. Gemini CLI retries on its own; if it gives up, try again or use another model.
• 404 and no longer available to new users: an older model name, such as gemini-2.5-flash, that Google has retired for new keys. Use a current one from /model.
• API key not valid: the key was refused. Check it in Google AI Studio.
• Invalid auth method selected: ~/.gemini/settings.json has no selectedType; write it as in "Connect it to Gemini".
• Anything else: Gemini CLI saves the full error report under /tmp and names the file in the message. Run gemini --debug for more, or see Google's troubleshooting guide.