# surrealdb.sh

> SurrealDB's documentation, served over SSH as a read-only filesystem. Built for AI coding agents: no account, no API key, no SDK, no MCP server, no HTML to parse. Run `ssh surrealdb.sh <command>` and search the docs with the shell tools you already have.

surrealdb.sh is a documentation endpoint, not a database. It cannot execute SurrealQL and stores no
user data. To run SurrealDB itself, start at https://surrealdb.com/docs.

## Endpoint

Host `surrealdb.sh`, SSH on port 22. Authentication is accepted unconditionally: any username, no
public key, no password, no account, no signup. There are two modes:

```bash
ssh surrealdb.sh                    # interactive shell, with tab completion
ssh surrealdb.sh <command>          # one-shot exec: clean stdout, no banner, no TTY
```

Agents should use the one-shot form. It prints nothing but the command's own output, so it composes
with pipes and is safe to parse.

## Filesystem

Docs are mounted read-only at `/surrealdb/docs`. The working directory is `/surrealdb`, `USER` is
`surreal` and `HOME` is `/surrealdb`. The entire filesystem is read-only: every write returns
`EROFS`, so redirecting output into a file will fail. This is an in-process bash emulation, not a
login shell on a machine, and `ssh` inside the sandbox is stubbed and exits 1.

Top-level directories under `/surrealdb/docs` mirror the content collections of
https://github.com/surrealdb/docs.surrealdb.com (`src/content` plus `public/integrations`,
flattened). As of this build:

    agent-memory/  agent-rules/  build/  explore/  index/  labs-items/  learn/  manage/  reference/

This is upstream's own taxonomy, not something this project controls, and it has changed before —
the `doc-`-prefixed scheme this file once described (`doc-surrealql/`, `doc-sdk-python/`, …) was
replaced upstream on 2026-09-10. Run `ls /surrealdb/docs` to get the current list rather than
trusting this one, and don't assume a directory matches a SurrealDB product/marketing term:
`/surrealdb/docs/surrealql` does NOT exist, `/surrealdb/docs/reference/query-language` does. Only
`*.md`, `*.mdx` and `*.mdc` files are present.

## Commands

```bash
# Explore
ssh surrealdb.sh ls /surrealdb/docs
ssh surrealdb.sh ls /surrealdb/docs/reference/query-language/statements

# Search
ssh surrealdb.sh grep -rl 'SELECT' /surrealdb/docs
ssh surrealdb.sh grep -rn 'DEFINE INDEX' /surrealdb/docs/reference/query-language

# Read
ssh surrealdb.sh cat /surrealdb/docs/reference/query-language/statements/select.mdx
ssh surrealdb.sh head -50 /surrealdb/docs/reference/query-language/statements/select.mdx

# Discover
ssh surrealdb.sh find /surrealdb/docs -name '*.mdx' -path '*reference/python*'

# Built-ins
ssh surrealdb.sh agents              # markdown snippet for AGENTS.md / CLAUDE.md / GEMINI.md
ssh surrealdb.sh agents >> AGENTS.md # the recommended one-time setup
ssh surrealdb.sh skill               # Agent Skill definition (SKILL.md)
ssh surrealdb.sh setup               # setup guide; pipe it: ssh surrealdb.sh setup | claude
ssh surrealdb.sh llms                # this file
```

Supported commands: `ls`, `cat`, `grep`, `find`, `head`, `tail`, `cd`, `pwd`, `echo`, `wc`, `sort`,
`uniq`, `tr`, `cut`, `sed`, `awk`, plus the built-ins `agents`, `skill`, `setup` and `llms`. Pipes,
globs and `&&` / `||` work.

## Behaviour to plan around

- Read-only and unauthenticated by design. Nothing you run here can mutate state, so any command is
  safe to retry.
- Caching: command output is cached in memory, keyed on the working directory plus the exact command
  string (1000 entries, 512 KiB of output per entry, per replica). Repeating an identical command is
  cheap.
- Rate limiting: no per-IP request rate limit is currently enforced. Please do not rely on that;
  keep request volume proportionate.
- Concurrency and timeouts: 100 concurrent connections in total, 10 per source IP, 60s idle timeout,
  600s maximum session, 10s per one-shot exec. An unscoped `grep -r` or `find` over the whole tree
  can hit the exec timeout, so scope it to a subdirectory.
- Freshness: docs are fetched when the image is built, so they track https://surrealdb.com/docs with
  a deploy-sized lag rather than in real time.
- Recommended pattern: `grep -rl '<keyword>' /surrealdb/docs` to locate files, then `head -50` to
  triage, then `cat` only what you need. Avoid reading the whole tree.

## Docs

- [SurrealDB documentation](https://surrealdb.com/docs): canonical HTML docs, same markdown source as this endpoint.
- [SurrealQL reference](https://surrealdb.com/docs/surrealql): query language reference, mirrored at `/surrealdb/docs/reference/query-language`.
- [Documentation source](https://github.com/surrealdb/docs.surrealdb.com): the upstream markdown this endpoint serves.

## Optional

- [surrealdb.sh](https://surrealdb.sh): human-readable overview of this service.
- [API catalog](https://surrealdb.sh/.well-known/api-catalog): RFC 9727 link set describing this endpoint.
- [robots.txt](https://surrealdb.sh/robots.txt): crawling policy — everything is allowed.
- [SurrealDB](https://surrealdb.com): the database itself.