After using Gemini-cli at work, I thought I'd try some coding agent also for my personal projects. I don't trust running them locally on my computer for privacy reasons, so instead I thought I'd run the agent on a small VPS I rent, 1GB of RAM, 1 CPU core.
I quickly discovered that just installing OpenCode pretty much killed that VPS. Those Gemini-cli based agents full node.js applications, with a myriad different dependencies. I started looking for some lightweight agent but even the most lightweight I could find (pi.dev) still seemed too much for me.
So I made my own. I used a handwritten agent I was using locally in the past for some experimentation and changed it a bit to bootstrap rudimentary coding agent out of it. Then I used itself to continue developing it.
I named it after Talos, it's written in Lua as a single hackable .lua file and it targets Linux. I suggest you add your API key to it by editing the script (it's hardcoded in it), drop the script in your ~/bin directory (or anywhere in your path), copy it also in an empty directory, and then start Talos inside the empty directory and ask it to modify itself. Then use your favorite tool to review the changes it makes, for example I like using Meld to view the differences between the running version and the modified version and to accept them into the running version before restarting it. If you need help, drop a comment here.
To run it you need to install Lua and the following Lua modules which you should be able to find in your repositories: socket ssl cjson ltn12 lfs posix readline
Lfs may be called luafilesystem or something like that in your repos. Posix and readline are optional but strongly recommended. Ltn12 and ssl may be part of luasec. Socket is the usual luasocket.
You will also need to make sure you have the following commands available: sh, timeout, tar, zstd, diff, bwrap, stty
Bwrap is bubblewrap, which is a chunky one and the reason why Talos doesn't work on anything but Linux. It is used for sandboxing so it's likely the most important dependency.
Here is the help page of Talos which should explain also most of its features:
Talos - interactive LLM agent
=============================
Talos is a command-line AI agent. Type a message at the prompt and press Enter to talk to it. Talos can reason, hold a conversation, and act on your working directory by calling tools (reading/writing files, running shell commands, searching, and more). It remembers context across sessions.
GETTING STARTED
- Just type and press Enter to send a message.
- Press Enter on an empty line to quit.
- For multiline input, start with Lua long-bracket syntax like [[, [=[, or [===[. Any number of equal signs is acceptable, as long as the closing marker matches: ]], ]=], or ]===]. The markers are stripped, and everything between them is sent as one message.
- Start with an optional session name: talos mysession
Each named session keeps separate history and memory under .talos/session-<session_name>/. With no name, .talos/ is used.
WHAT TALOS CAN DO
- Hold a conversation and answer questions.
- Read, create, delete, search, and manipulate files in the working dir.
- Run sandboxed shell commands, and unsandboxed shell commands with your approval.
- Automatically resummarize the conversation if it grows too long, compressing messages into it's persistent memory.
SHELL COMMAND SAFETY
Normal run_shell commands are sandboxed inside the working directory and have no network. Unsandboxed run_shell commands can access host paths/network and require per-command approval or exact pre-approval:
y / yes - run it once and show output to Talos
n / no - decline
a / always - run and pre-approve this exact command
p / preview - run it, show you the output, then ask whether Talos may see the output
h / help - explain the options
:reason - decline, and send reason to Talos
Commands are killed if they run longer than 60 seconds.
PATH SAFETY
All file tools are confined to the working directory. Absolute paths and paths that escape the directory (via ..) are rejected. Only unsandboxed shell commands should be able to escape the working directory, and those need your approval to run.
SLASH COMMANDS
General
/help Show this guide.
/test Run live API self-tests.
/leaks Print a sandbox leak report locally; the report is not sent to the model.
Backups
/backup Write a compressed tar archive to .talos/backups/. Backups include everything in your working directory, including Talos's state.
Talos also creates an automatic backup before conversation turns if the newest backup is over 30 minutes old.
/backup list List backups from oldest to newest.
/backup prune Delete half the backups while keeping the latest backup, then show total backup size.
/backup restore N Restore backup number N, after making a safety backup, then quit.
/diff [N] Show a unified diff between the current workspace and backup N, or the latest backup.
Sandbox mounts
/mount list List persistent sandbox mounts.
/mount ro SRC DST Mount host SRC read-only at sandbox DST.
/mount rw SRC DST Mount host SRC read-write at sandbox DST.
/mount tmpfs DST Mount temporary writable memory at sandbox DST.
/mount remove N Remove sandbox mount number N.
Skills
/skill list List configured skill search paths and discovered skills.
/skill add PATH Add a skill search path with symlinks blocked. Defaults are .agents/skills/ and ~/.agents/skills/.
/skill addsl PATH Add a trusted skill search path with symlinks allowed.
/skill remove N Remove configured skill search path number N.
Memory and history
/summarize Fold older messages into long-term memory now.
/summarize all Fold all messages into long-term memory now.
/memory Print the current long-term memory.
/clear messages Erase the conversation history.
/clear memory Erase the long-term memory.
/clear cost Reset the session's cost.
/clear pre-approved Erase pre-approved shell commands.
/clear home Erase the persistent sandbox home directory.
/clear all Erase messages, memory, cost, pre-approved commands, and sandbox home.
Transfer
/upload PORT DIR Open a temporary browser upload page on PORT that saves files under DIR; use the page's stop button to end the command.
/download PORT FILE Open a temporary browser download page on PORT that serves FILE; use the page's stop button to end the command.
COST
Each session tracks its API cost, shown after responses and on startup.
You can download Talos from here.
