Skip to main content
These are optional but strongly recommended steps. A well-configured environment means your agent survives reboots, recovers from crashes, and stays accessible no matter where you are.

​
Keep the agent running with PM2

By default, remoteagent start launches a background process that dies if the server reboots. To make it survive reboots automatically, use PM2:
Start your agent via PM2 instead of the built-in background mode:
Save the process list and enable startup on boot:
Run the command PM2 prints (it looks like sudo env PATH=... pm2 startup systemd -u ...) to register it with your init system. To check status and logs:
If you have multiple agents (Pro plan), start each one with a different PM2 name: pm2 start remoteagent --name "project-a" -- start --agent <agentId>.

​
Install Git

Most AI coding runners (Claude Code, Aider, Gemini) will try to run git commands. Make sure Git is installed before pairing:
Verify:
Also configure your identity so commits work without prompts:

​
Set a default project directory

Always run remoteagent init from the root of your project. The working directory is saved in the agent config and used as the base path for every command. Using ~/ or /tmp as the project path will confuse the runner. A good layout:

​
Keep your runner authenticated

RemoteAgent.CHAT doesn’t store your AI credentials — the runner must be authenticated on the machine. Claude Code (OAuth): tokens expire after 1 year. You can generate a long-lived token during remoteagent init or refresh it later:
Claude SDK: your API key is stored in the agent config file (~/.remoteagent/agents/{agentId}.json). Rotate it when needed:
Gemini / Aider: check that the relevant environment variable (GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.) is set in the shell profile (~/.bashrc or ~/.zshrc) so it’s available on every session.

​
Use a dedicated low-privilege user

Avoid running RemoteAgent.CHAT as root. Create a dedicated system user with access only to your project directories:
Run the agent as that user:
This limits the blast radius if a prompt accidentally runs a destructive command.

​
Protect your config files

The agent config files contain your API key and agent token in plain text. Ensure only your user can read them:
These permissions are set automatically by remoteagent init, but worth verifying if you’ve moved files manually.

​
Set up a swap file (low-memory servers)

AI runners (especially Claude SDK and Aider) can use significant memory. On VPS instances with 1 GB RAM or less, adding swap prevents out-of-memory crashes:

​
Keep RemoteAgent.CHAT up to date

New versions ship bug fixes and runner improvements. Update with:
This updates the binary in-place and automatically restarts any running agents. Your config and agents are untouched.

​
Test the connection before going remote

Before relying on RemoteAgent.CHAT from your phone, verify the full loop works locally:
  1. Start the agent: remoteagent start
  2. Open Telegram and send /status to the bot
  3. Send a simple prompt: "hello world"
  4. Confirm you see the output in Telegram
If /status shows the agent as online and you get a response, the setup is solid.