Metadata-Version: 2.1
Name: vlambda
Version: 1.0.0
Summary: An ASGI-like server for Python lambdas, written in V.
License: MIT
Requires-Python: >=3.14
Classifier: Programming Language :: Other
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Description-Content-Type: text/markdown

# vlambda

An ASGI-like server for Python lambdas, written in V. Uses [vcraft](https://github.com/rroblf01/vcraft) for the V↔Python bridge.

**Live at:** https://vlambda.ricardorobles.es

## What is vlambda?

vlambda lets you write Python functions ("lambdas") and serve them as HTTP endpoints. It's like AWS Lambda, but self-hosted, with no cold start in persistent mode and a fresh sandbox per invocation in Docker (~10-20 ms p50).

```python
def handler(request):
    return {"msg": "hello", "path": request.path}
```

POST that code to `/vlambda` and it becomes `GET /f/<slug>` instantly.

## Features

- **No cold starts in persistent mode** — Docker uses a fresh Landlock process per invocation, which adds a small startup cost
- **Fast** — ~3,000 req/s in-process; the Docker fork sandbox adds a few milliseconds per invocation
- **Auth** — JWT-based authentication with per-user ownership
- **Web UI** — Dashboard for managing lambdas, code editor, metrics
- **Async invocation** — Fire-and-forget with task tracking
- **KV store** — per-lambda typed key/value state with TTL and atomic increments
- **Controlled egress** — allow-listed HTTPS calls from the sandbox via `request.fetch`
- **Schedules** — persistent five-field cron jobs with timezones, run history and a single leader
- **OpenAPI** — owner-scoped spec, metadata editor and CLI export
- **Sandbox** — Landlock + seccomp in Docker, plus restricted Python builtins and blocked modules
- **Metrics** — Prometheus-compatible + Chart.js dashboard
- **Per-lambda method** — GET, POST, PUT, PATCH, DELETE
- **Naming** — Human-readable names for lambdas
- **Multi-file projects** — ZIP uploads, file editor, `requirements.txt`/`pyproject.toml`
- **Versions and aliases** — rollback and `prod`/`staging` aliases
- **PyPI packages** — install per lambda/project from the UI
- **Persistent metrics and logs** — survive restarts, queryable by slug/name
- **CORS** — opt-in per-origin CORS for `/f/` responses, with `OPTIONS` preflight
- **Static files** — projects serve `index.html`, CSS, JS and assets at `/f/<slug>/<path>`
- **API tokens** — long-lived tokens with scopes and revocation
- **Export / import / duplicate** — move lambdas and projects as JSON
- **POC templates** — HTML + `fetch`, webhook, JSON API, static site
- **Free-threaded builds** — `cp314t`/`cp315t` wheels

## Roadmap

1.0 is the current release line: single-host deployments on Linux, data
lifecycle (backup/restore and schema versions), security hardening,
operational tooling and complete documentation. Multi-host active/active is out
of scope, and Firecracker/microVM-per-invocation isolation is not part of 1.0.
See [docs/ROADMAP-1.0.0.md](docs/ROADMAP-1.0.0.md); the 0.4.0 design notes
remain in [docs/ROADMAP-0.4.0.md](docs/ROADMAP-0.4.0.md).

## Installation

```bash
uv pip install vlambda
```

Or with pip:
```bash
pip install vlambda
```

The production container image is published as
`ghcr.io/rroblf01/vlambda:<version>` for `linux/amd64` and `linux/arm64`.

## Usage

```bash
export VLAMBDA_SECRET="$(openssl rand -hex 32)"
python -m vlambda --port 8080 --sqlite_path ./vlambda.db --num_coroutines 10
```

Or with environment variables:
```bash
VLAMBDA_SECRET="$(openssl rand -hex 32)" \
VLAMBDA_PORT=8080 VLAMBDA_DB=./vlambda.db VLAMBDA_COROUTINES=10 python -m vlambda
```

For a local development instance without TLS or real users you can set
`VLAMBDA_DEV=1` instead; the server warns and uses an insecure JWT secret.

Then open http://localhost:8080/ in your browser. `python -m vlambda --version`
prints the running package version; `/health` and `/ready` return it in JSON.

## Documentation

- [API reference](docs/API.md)
- [CLI reference](docs/CLI.md)
- [Compatibility and versioning](docs/COMPATIBILITY.md)
- [Upgrading](docs/UPGRADING.md)
- [Operations](docs/OPERATIONS.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)

## Build a POC in five minutes

1. Open the UI and log in.
2. Pick a template in **New lambda** (`JSON API`, `Webhook receiver`,
   `Form receiver`, `HTML page`…) and create it.
3. Open the invoke URL `https://your-host/f/<slug>`.
4. Need files? Upload a ZIP in **Upload project**; anything in the project is
   served at `/f/<slug>/<path>` and any unknown path runs `handler(request)`.

More complete examples live in [`examples/`](examples/): a static site, an
HTML + `fetch` POC, a webhook receiver and a JSON API.

## API tokens

Create a token in **System → API tokens**, or with the API:

```bash
curl -X POST "$VLAMBDA_URL/tokens" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci","scopes":["read","write"]}'
```

The response contains the token (`vl_…`) once. Use it as
`Authorization: Bearer vl_…`. Scopes are `read`, `write` and `admin`; revoke a
token with `DELETE /tokens/<id>`. Tokens do not expire.

## Docker + Dokploy

The repository includes a production image (`Dockerfile`, installs from PyPI) and
a development image (`Dockerfile.dev`, builds the local wheel). Both use a
free-threaded Python 3.15 venv, a pre-warmed fork supervisor and a fresh
Landlock + seccomp child per invocation, and expose plain HTTP on port `8080`;
Dokploy (or another proxy) handles TLS and the public domain.

The sandbox needs no extra Docker flags, capabilities or host sysctl changes.
It requires a Linux kernel with Landlock (5.13+; Ubuntu 22.04+, Debian 12+).

```bash
export VLAMBDA_SECRET="$(openssl rand -hex 32)"
export VLAMBDA_ADMIN_TOKEN="$(openssl rand -hex 32)"
docker compose -f docker/compose.yml up -d --build
```

With Dokploy, create an application from the image, map the domain to container
port `8080`, and set `VLAMBDA_SECRET` and `VLAMBDA_ADMIN_TOKEN`. Dokploy terminates
TLS, so the container does not manage certificates.

See `docker/README.md` for details, limits and the reset command.

## CLI Options

| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--port` | `VLAMBDA_PORT` | 8080 | Listen port |
| `--sqlite_path` | `VLAMBDA_DB` | ./vlambda.db | SQLite database path |
| `--num_coroutines` | `VLAMBDA_COROUTINES` | 10 | Worker pool size |
| `--max_body_size` | `VLAMBDA_MAX_BODY` | 1048576 | Max request body (bytes) |
| | `VLAMBDA_MAX_RESPONSE` | 10485760 | Max lambda response body (bytes) |
| | `VLAMBDA_MAX_TASKS` | 10000 | Queued async tasks before new tasks are rejected |
| | `VLAMBDA_MAX_TASKS_PER_OWNER` | 100 | Queued async tasks per user before new tasks are rejected |
| | `VLAMBDA_TRUST_PROXY` | 0 | Trust `X-Forwarded-For` for the client IP (enable only behind a proxy that overwrites it) |
| `--rate_limit` | `VLAMBDA_RATE_LIMIT` | 100 | Requests/sec per IP |
| `--invoke_timeout` | `VLAMBDA_TIMEOUT` | 30 | Lambda invocation timeout (s) |
| `--max_memory_mb` | `VLAMBDA_MAX_MEMORY_MB` | 0 | RAM limit (0=unlimited) |
| `--cors_origin` | `VLAMBDA_CORS` | *(none)* | CORS allowed origin; set `*` or an explicit origin to enable CORS |
| `--cert` | `VLAMBDA_CERT` | | TLS certificate path |
| `--key` | `VLAMBDA_KEY` | | TLS key path |
| | `VLAMBDA_REGISTRATION` | 1 | Allow public registration (`0` disables it; the production image sets `0`) |
| | `VLAMBDA_LOGIN_MAX_FAILURES` | 5 | Failed logins before a temporary block |
| | `VLAMBDA_LOGIN_WINDOW` | 300 | Failure window in seconds |
| | `VLAMBDA_LOGIN_BLOCK` | 300 | Block duration in seconds |
| | `VLAMBDA_REGISTER_MAX` | 5 | Registrations allowed per IP in the window |
| | `VLAMBDA_REGISTER_WINDOW` | 600 | Registration window in seconds |
| | `VLAMBDA_PASSWORD_MIN_LENGTH` | 12 | Minimum password length |
| | `VLAMBDA_USER_RATE_LIMIT` | rate limit | Requests/s per authenticated user (`0` follows the global limit) |
| | `VLAMBDA_AUDIT_RETENTION_DAYS` | 90 | Days of administrative audit entries to keep (`0` keeps all) |
| | `VLAMBDA_BACKUP_KEY` | encryption key | Key for `vlambda backup --encrypt`; keep it out of the backup |
| | `VLAMBDA_SANDBOX` | auto | `auto`, `fork`, `landlock`, `nsjail` or `process` (`auto` selects fork when Landlock + seccomp are available) |
| | `VLAMBDA_SECCOMP_MODE` | allowlist | `allowlist` (default) or `denylist` fallback for unusual runtimes |
| | `VLAMBDA_CORS` | *(none)* | Allowed CORS origin for `/f/`; set `*` or an explicit origin to enable |
| | `VLAMBDA_PIP_INDEX_URL` | PyPI | Index used when installing lambda packages |
| | `VLAMBDA_PIP_EXTRA_INDEX_URL` | | Additional allowed package index |
| | `VLAMBDA_PIP_REQUIRE_HASHES` | 0 | Require hashes in `requirements.txt` (`--require-hashes`) |
| | `VLAMBDA_METRICS_STATS_TTL` | 15 | Cache for percentile stats in seconds (`0` disables it) |
| | `VLAMBDA_DEV` | 0 | Allow local development without `VLAMBDA_SECRET` |
| | `VLAMBDA_SQLITE_JOURNAL` | auto | `wal` or `delete`; auto falls back to `delete` when CPython and system SQLite versions differ |
| | `VLAMBDA_RESP_CACHE_TTL` | 0 | GET response cache TTL in seconds (0 disables it) |
| | `VLAMBDA_CACHE_BACKEND` | memory | `memory`, `file` or `redis` for the optional response cache |

vlambda normally uses SQLite WAL. When CPython bundles a SQLite version
different from the system `libsqlite3` used by the V extension (for example on
Python 3.15), it automatically falls back to the rollback journal to avoid
cross-library WAL corruption. Set `VLAMBDA_SQLITE_JOURNAL=wal` or `delete` to
override it.

The GET response cache is disabled by default because a handler can depend on
headers, cookies, `request.env`, time or other request state. Enable it only for
stateless, idempotent GET lambdas; handlers that read request context, log,
`random` or `time.time` are skipped automatically.

## API

### Authentication
- `GET /config` — Public runtime flags (whether registration is open)
- `POST /register` — Register user (body: `username:password`); returns `403` when registration is disabled
- `POST /login` — Login (body: `username:password`) → JWT token
- `POST /password` — Change your password (body: `old:new`, or JSON `{"old":"...","new":"..."}` when the old password contains a colon); revokes existing sessions
- `POST /admin/users` — Create a user with `X-Admin-Token` and body `username:password` (for closed registration)

### Admin token

vlambda does **not** have an admin user account or an `is_admin` column. The
admin is a deployment secret, `VLAMBDA_ADMIN_TOKEN`, sent as
`X-Admin-Token`. With registration closed (the production default), use it to
create the first users:

```bash
curl -X POST https://your-host/admin/users \
  -H "X-Admin-Token: $VLAMBDA_ADMIN_TOKEN" \
  -d "alice:change-me-please-123"
```

The token also protects `/admin/password` (reset a password),
`/admin/reset` (wipe all data) and `/admin/audit` (read administrative audit
entries), plus `/shutdown`:

```bash
curl -X POST https://your-host/admin/password \
  -H "X-Admin-Token: $VLAMBDA_ADMIN_TOKEN" \
  -d "alice:new-password-123"

curl https://your-host/admin/audit?limit=50 \
  -H "X-Admin-Token: $VLAMBDA_ADMIN_TOKEN"
```

The token is not stored in SQLite, cannot log in, and does not own lambdas.
It remains valid across a data reset; users do not. To see every user's
tasks, metrics, logs or OpenAPI document, send the admin token alongside a
valid Bearer token. A reset does not change `VLAMBDA_ADMIN_TOKEN` or
`VLAMBDA_SECRET`.

### Lambdas (requires auth)
- `POST /vlambda?method=GET&name=my-lambda` — Create lambda (body: Python code)
- `GET /vlambda` — List lambdas (pipe-delimited)
- `GET /vlambda?format=json` — List lambdas as JSON
- `GET /vlambda/<slug>` — Get lambda code
- `PUT /vlambda/<slug>?method=POST&name=new-name` — Update lambda
- `DELETE /vlambda/<slug>` — Delete lambda
- `GET /vlambda/<slug>/env` — List environment variables (secrets masked)
- `PUT /vlambda/<slug>/env` — Replace vars/secrets: `{"vars": {...}, "secrets": {...}}`

### API tokens (requires auth)
- `POST /tokens` — Create a token: `{"name":"ci","scopes":["read","write"]}`; `admin` implies read/write and allows token management
- `GET /tokens` — List tokens (never returns the secret)
- `DELETE /tokens/<id>` — Revoke a token

Tokens are accepted anywhere a JWT is accepted. `read` allows listing and
reading, `write` allows mutating lambdas/projects, and `admin` allows token
management. The `/admin/*` endpoints always require the deployment admin token
(`X-Admin-Token`), not an API token scope.

### Export / import
- `GET /vlambda/<slug>/export` — Export code or project files as JSON
- `POST /vlambda/import` — Create from an exported JSON body
- `POST /vlambda/<slug>/duplicate` — Copy a lambda or project

Project exports include text files. Binary files are listed in
`skipped_files` and are not copied.

### Invocation
- `GET/POST/PUT/PATCH/DELETE /f/<slug>` — Invoke lambda (method must match)
- `OPTIONS /f/<slug>` — CORS preflight (returns `204`)
- `GET /f/<slug>/<path>` — Serve a project file, or invoke the handler if the
  file does not exist
- `POST /async/<slug>` — Async invoke (returns task_id)
- `GET /task/<id>` — Get async task result

### Projects
- `POST /vlambda?project=1&entry=main.py` — Upload a ZIP project (base64 body)
- `GET /project/<slug>` — Read project files
- `PUT /project/<slug>` — Save project files
- `GET /f/<slug>/` — Serve `index.html`
- `GET /f/<slug>/<path>` — Serve a static file (`vendor/`, `.git/` and `..` blocked)

### Versions and aliases
- `GET /vlambda/<slug>/versions` — List versions
- `GET /vlambda/<slug>/version/<n>` — Read a version
- `POST /vlambda/<slug>/rollback?version=<n>` — Roll back
- `GET /vlambda/<slug>/aliases` — List aliases
- `POST /vlambda/<slug>/alias?name=prod&version=<n>` — Create alias
- `GET /f/<slug>?alias=prod` — Invoke an alias

### Packages
- `GET /vlambda/<slug>/packages` — List requirements
- `POST /vlambda/<slug>/packages` — Install PyPI packages into the vendor dir

For production, pin versions in `requirements.txt` and point
`VLAMBDA_PIP_INDEX_URL` at a controlled mirror (or use
`VLAMBDA_PIP_REQUIRE_HASHES=1` with hashes). Without that, package
installation trusts whatever PyPI serves at upload time.

### KV, egress and schedules
- `GET/PUT/DELETE /vlambda/<slug>/kv[/<key>]` — Read, write or delete KV entries
- `GET/PUT /vlambda/<slug>/egress` — Read or replace the egress allow-list
- `GET/POST /vlambda/<slug>/schedules` — List or create schedules
- `PUT/DELETE /vlambda/<slug>/schedules/<id>` — Update or delete a schedule
- `POST /vlambda/<slug>/schedules/<id>/run` — Run a schedule now
- `GET /vlambda/<slug>/schedules/<id>/runs` — Run history

### Metadata and OpenAPI
- `GET/PUT /vlambda/<slug>/meta` — Summary, tags and description
- `GET /openapi.json` — Owner-scoped OpenAPI 3.1 document

### Monitoring (requires auth)
- `GET /health` — Health check with the running version
- `GET /ready` — Readiness with the running version
- `GET /metrics` — Prometheus metrics
- `GET /metrics/json` — Live JSON metrics
- `GET /metrics/history?days=N&slug=` — Raw persisted metrics
- `GET /metrics/stats?days=N&slug=` — p50/p95/p99
- `GET /metrics/aggregate?days=N&slug=` — Per-lambda aggregates
- `GET /metrics/summary?days=N&slug=` — Daily rollups
- `GET /metrics/export?days=N&slug=` — CSV export
- `DELETE /metrics/history?days=N&slug=` — Delete metrics older than N days (`days=0` deletes all)
- `GET /logs/history?days=N&slug=` — Persisted lambda logs
- `DELETE /logs/history?days=N&slug=` — Delete logs older than N days (`days=0` deletes all)
- `GET /pool/stats`, `GET /dlq`
- `POST /shutdown` — Graceful shutdown (requires `X-Admin-Token`)

## Logging

Lambdas can persist structured logs with `request.log()`:

```python
def handler(request):
    request.log("processing " + request.path)
    request.log("debug details", "debug")
    return {"ok": True}
```

Logs are stored in the metrics database and can be queried with
`GET /logs/history?days=1&slug=<slug>`. The UI Logs view shows them alongside
invocations. The "Save logs" template in the editor is a ready-to-run example.

Metrics and logs are scoped to the authenticated user. A request that also
carries the deployment admin token (`X-Admin-Token`) can query all users
through the API; the admin token is not a login credential by itself.

Metrics and logs are pruned after `VLAMBDA_METRICS_RETENTION` days (default 7).
From the UI you can also prune data older than the selected period, or delete
all matching rows, with the current lambda filter applied.

## Lambda Format

Every lambda must define a `handler` function. The canonical contract returns a
`Response`; returning a `dict`, `str` or `bytes` is still accepted as shorthand:

```python
from vlambda import Response

def handler(request):
    return Response.json(
        {"msg": "hello", "path": request.path},
        status=201,
        headers={"X-Example": "yes"},
    )
```

The `request` object has: `method`, `path` (without the query string),
`query_string`, `query`, `headers`, `cookies`, `body`, `remote_ip`, `host`,
`scheme`, `request_id`, `slug`, `env`, and helpers `header()`, `json()`,
`form()` and `log()`.

`Response` supports `json()`, `text()`, `html()`, `redirect()`, `no_content()`,
status codes, headers, cookies and binary bodies.

Handlers may also be coroutine functions. vlambda awaits the coroutine and
serializes its value exactly like a synchronous return:

```python
async def double(value):
    return value * 2

async def handler(request):
    return {"values": [await double(n) for n in (1, 2, 3)]}
```

Await local coroutines or helpers you define with `async def`. The `asyncio`
module stays blocked because it exposes sockets indirectly.

Safe builtins: `abs`, `all`, `any`, `bool`, `dict`, `enumerate`, `filter`, `float`, `int`, `len`, `list`, `map`, `max`, `min`, `range`, `reversed`, `round`, `set`, `sorted`, `str`, `sum`, `tuple`, `zip`, `print`, etc.

Blocked modules: `os`, `posix`, `subprocess`, `sys`, `importlib`, `ctypes`, `socket`, `_socket`, `urllib`, `http`, `shutil`, `pathlib`, `io`, `pickle`, `marshal`, `resource`, `fcntl`, `mmap`, `sqlite3`, etc.

Safe modules: `json`, `math`, `re`, `datetime`, `collections`, `itertools`, `functools`, `hashlib`, `base64`, `string`, `random`, `statistics`, etc.

### Security

With the Docker default (`VLAMBDA_SANDBOX=fork`), user code runs in a fresh
runner process confined with Landlock and seccomp.
Landlock limits the filesystem to `/opt`, `/usr`, `/lib`, `/etc`, the current
project/vendor and a private temporary directory; `/data`, `/proc`, `/sys` and
the rest of the server cannot be read or listed. seccomp blocks TCP/UDP and every
non-Unix socket, cross-process signals, `ptrace`, `mount`, namespace changes and
similar syscalls. Only `AF_UNIX` client sockets to the local capability broker
are allowed. Do not mount the Docker socket, cloud metadata proxies or other
privileged Unix sockets into the container: the sandbox needs Unix sockets for
the broker and cannot distinguish them from other local sockets. Resource
limits are applied too, and each invocation gets a fresh process.

The plain `python -m vlambda` command without `VLAMBDA_SANDBOX` uses the
in-process pool and is a development mode: lambdas run inside the server process
with only Python-level restrictions. Use `VLAMBDA_SANDBOX=fork` (Docker default),
`landlock`, `process` or `nsjail` for any untrusted code.

The production Docker image closes public registration by default. Create
users with `POST /admin/users` and `X-Admin-Token`, or set
`VLAMBDA_REGISTRATION=1` to open registration. Login attempts are throttled per
username and source IP after `VLAMBDA_LOGIN_MAX_FAILURES` failures.

At startup vlambda checks that the project, package and cache directories are
writable and, when `VLAMBDA_SANDBOX=fork`/`landlock` is selected, that Landlock
and libseccomp are available. It refuses to start instead of silently running
unsandboxed.

A daily data reset removes state, but it does not undo a kernel-level escape.
Keep this deployment disposable and do not store valuable secrets in it; for
stronger isolation use gVisor, Firecracker or one container per tenant.

## Environment and secrets

Set per-lambda variables with `PUT /vlambda/<slug>/env`:

```json
{
  "vars": {"PLAIN": "hello"},
  "secrets": {"TOKEN": "s3cret"}
}
```

Secrets are encrypted at rest, masked by the API and decrypted only for that
lambda's runner. Code lambdas read them from `request.env`; projects also see
them in `os.environ`. Use a dedicated `VLAMBDA_ENCRYPTION_KEY` so rotating
`VLAMBDA_SECRET` (JWT signing) does not require re-encrypting secrets.

`request.headers` deliberately hides `Authorization`, `Proxy-Authorization`,
`Cookie`, `X-Api-Key` and `X-Admin-Token` from lambda code. A handler cannot
read or forward the caller's credentials.

To rotate the encryption key, stop the server and re-encrypt the stored secrets
offline:

```bash
python -m vlambda backup --out before-rotate.tar.gz --encrypt
python -m vlambda secrets rotate \
  --old-key "$OLD_ENCRYPTION_KEY" --new-key "$NEW_ENCRYPTION_KEY"
```

The command is idempotent and reports how many rows it rotated. Every secret
carries a short key identifier, so a wrong old key fails closed instead of
writing garbage.

## KV store

Every lambda has a small persistent key/value store, isolated by lambda and
accessible through an allow-listed capability broker rather than a database
connection in the sandbox.

```python
def handler(request):
    hits = request.kv.incr("hits")
    request.kv.set("last", {"path": request.path}, ttl=3600)
    return {"hits": hits, "last": request.kv.get("last")}
```

Projects use the same API with `from vlambda import kv`. Values can be strings,
numbers, booleans, null, JSON documents or bytes; `incr()` is atomic and `ttl`
is optional. Limits are 256 keys, 64 KiB per value and 1 MiB per lambda.

Management API (owner only, `X-Admin-Token` not needed):

- `GET /vlambda/<slug>/kv?prefix=` — list
- `GET /vlambda/<slug>/kv/<key>` — read
- `PUT /vlambda/<slug>/kv/<key>` — write `{"value": ..., "ttl": 3600}`
- `DELETE /vlambda/<slug>/kv/<key>` — delete one key
- `DELETE /vlambda/<slug>/kv` — clear the store

The UI exposes a KV card in the code and project editors.

## Egress

Lambdas cannot open TCP sockets. They can call allow-listed hostnames through
the capability broker:

```python
def handler(request):
    response = request.fetch("https://api.example.com/items", timeout=5)
    return {"status": response.status, "data": response.json()}
```

Projects use `from vlambda import fetch`. Supported methods are `GET`, `HEAD`,
`POST`, `PUT`, `PATCH` and `DELETE`; pass `data=` for raw bodies or
`json_payload=` for JSON. The response exposes `status`, `headers`, `body`,
`text` and `json()`.

Configure the allow-list per lambda (`GET/PUT /vlambda/<slug>/egress`):

```bash
python -m vlambda egress <slug> --set api.example.com --set "*.example.org"
```

Matching is exact, or `*.example.org` for the apex and subdomains. HTTPS is
required by default; set `VLAMBDA_EGRESS_ALLOW_HTTP=1` for local development.
Private, loopback, link-local and reserved addresses are rejected; set
`VLAMBDA_EGRESS_ALLOW_PRIVATE=1` only for tests. Redirects are not followed.
Each invocation is limited to 20 calls, 1 MiB request bodies and 2 MiB
responses, with a 10 s maximum timeout. Denied hosts are logged without query
strings.

## Schedules

Create persistent cron jobs per lambda:

```bash
python -m vlambda schedule create <slug> --name nightly --cron "0 3 * * *" \
  --method POST --path /schedule --payload '{"job": "cleanup"}'
python -m vlambda schedule list <slug>
python -m vlambda schedule run <slug> <id>
python -m vlambda schedule runs <slug> <id>
python -m vlambda schedule delete <slug> <id>
```

Supported expressions use five fields (`minute hour day-of-month month weekday`),
with lists, ranges and steps, plus month/day names and IANA timezones. The
scheduler runs one leader per database lease; overlapping runs are skipped and
windows missed by more than `VLAMBDA_SCHEDULE_GRACE` seconds are recorded as
`missed`. Run history is retained for `VLAMBDA_SCHEDULE_RETENTION` days (7 by
default, max 1000 runs per schedule).

API:

- `GET/POST /vlambda/<slug>/schedules`
- `PUT/DELETE /vlambda/<slug>/schedules/<id>`
- `POST /vlambda/<slug>/schedules/<id>/run`
- `GET /vlambda/<slug>/schedules/<id>/runs`

The UI exposes a schedules card in the code and project editors.

## gVisor

For a second isolation boundary, run the container with the gVisor runtime:

```bash
docker run --runtime=runsc ... ghcr.io/rroblf01/vlambda:latest
# or merge the compose override:
docker compose -f docker/compose.yml -f docker/compose.gvisor.yml up -d
```

Kubernetes uses `runtimeClassName: gvisor` on the pod. The internal fork +
Landlock + seccomp sandbox remains active. `scripts/gvisor-smoke.sh` builds the
image, runs the health check under `runsc` and skips cleanly when gVisor is not
installed. Firecracker/microVM-per-invocation is not part of 1.0.

## High availability (single host)

1.0 supports multiple replicas on one host sharing a local `/data` volume.
SQLite WAL, a scheduler lease, task claiming and graceful drain keep scheduled
runs and tasks single-execution across replicas.

```bash
docker compose -f docker/compose.ha.yml up -d --build --scale vlambda=2
```

The sample puts nginx in front of two replicas. Do not place SQLite on NFS; use
a local volume on the same host. Multi-host HA needs an external database and is
not part of 1.0.

Relevant settings:

- `VLAMBDA_INSTANCE_ID` — unique replica name (defaults to hostname:pid)
- `VLAMBDA_DRAIN_TIMEOUT` — graceful shutdown wait (seconds, default 20)
- `VLAMBDA_TASK_LEASE` — task claim lease (seconds, default 600)
- `VLAMBDA_SCHEDULE_GRACE` / `VLAMBDA_SCHEDULE_RETENTION` — cron behavior
- `/ready` returns `503` while a replica is draining

## OpenAPI

Every lambda can carry `summary`, `tags` and `description` metadata, editable
from the code/project editor or `PUT /vlambda/<slug>/meta`. The generated spec is
available at `/openapi.json` (authenticated and owner-scoped by default; set
`VLAMBDA_OPENAPI_PUBLIC=1` for a public spec). Import it into Postman, Insomnia,
Scalar, Swagger UI or any OpenAPI 3.1 client.

```bash
python -m vlambda openapi --out openapi.json
```

The spec describes `/f/<slug>` for every owned lambda, its method, request body
for write methods, generic JSON/text/binary responses and the `X-Request-Id`
header. Project static files are described under `/f/<slug>/{path}`.

## CLI

The CLI talks to a running server and uses `VLAMBDA_URL`/`VLAMBDA_TOKEN` or
`--url`/`--token`:

```bash
python -m vlambda deploy main.py --name my-lambda --method GET
python -m vlambda invoke <slug>
python -m vlambda logs --slug <slug> --days 1
python -m vlambda env <slug> --set PLAIN=hello --secret TOKEN=s3cret
python -m vlambda kv <slug> --set hits=0 --ttl 3600
python -m vlambda kv <slug> --get hits
python -m vlambda egress <slug> --set api.example.com
python -m vlambda schedule list <slug>
python -m vlambda openapi --out openapi.json
python -m vlambda task <task-id>
python -m vlambda backup --out backup.tar.gz
python -m vlambda restore --from backup.tar.gz --force
python -m vlambda secrets rotate --old-key "$OLD" --new-key "$NEW"
```

## Web UI

Open http://localhost:8080/ in your browser for the dashboard:
- Login/Register
- Lambda dashboard with search, filter and pagination
- CodeMirror editor with Python highlighting
- Multi-file project editor and ZIP upload
- Versions, rollback and aliases
- PyPI package installation
- API playground
- Persistent metrics with charts and filters
- Logs viewer with `request.log()`
- System status and frontend log drawer

## Reset

The demo can be wiped with:

```bash
python -m vlambda reset --yes --url http://127.0.0.1:8080 --token "$VLAMBDA_ADMIN_TOKEN"
```

A reset also invalidates existing JWT sessions and API tokens.

1.0 starts with a fresh schema and refuses to open a pre-1.0 database. To move
an existing deployment to 1.0, stop the server and wipe the database files:

```bash
python -m vlambda reset --yes --wipe
```

Install 1.0 first so this command exists. It removes the main and metrics
databases plus project, package and cache data. Copy the data volume first if
you need to keep anything; the old schema is not migrated automatically.

For a disposable demo, run it from cron every day. `--online-only` prevents the
CLI from touching SQLite directly if the server is down or rejects the request:

```cron
0 3 * * * flock -n /run/vlambda-reset.lock docker exec -e VLAMBDA_ADMIN_TOKEN="..." <container> /opt/venv/bin/python -m vlambda reset --yes --online-only --url http://127.0.0.1:8080 >> /var/log/vlambda-reset.log 2>&1
```

## Backup and restore

Backups are self-contained archives of the main SQLite database, the
metrics/logs database and the project tree. The main database is copied with
SQLite's online backup API, so a backup is safe while the server is running.
Restoring is offline: stop the server first.

```bash
# Safe while the server is running
python -m vlambda backup --out /data/backups/vlambda-$(date +%F).tar.gz

# Stop the server before restoring
python -m vlambda restore --from /data/backups/vlambda-2026-11-04.tar.gz --force
```

Add `--with-packages` to include the per-lambda/project package vendor
directories. Restores verify `PRAGMA integrity_check`, the schema version and the
encryption-key fingerprint. Use the same `VLAMBDA_SECRET` or
`VLAMBDA_ENCRYPTION_KEY`; if you accept that encrypted secrets will not decrypt,
pass `--allow-key-mismatch`.

Both databases expose a schema version through `PRAGMA user_version`. A build
refuses to open a database written by a newer schema, so an older backup is the
safe rollback path.

## Performance

| Metric | Value |
|--------|-------|
| Cold start | 0ms in persistent mode; fresh sandbox process in Docker |
| Warm invocation (in-process) | ~0.3ms |
| Warm invocation (Docker fork sandbox) | ~10-20ms p50 |
| Throughput (concurrent, free-threaded) | ~3,000 req/s in-process |
| Response cache | Opt-in via `VLAMBDA_RESP_CACHE_TTL`; ~100x faster for stateless GETs |

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Browser   │────▶│  V HTTP      │────▶│  Python     │
│   (UI)      │◀────│  Server      │◀────│  Pool       │
└─────────────┘     │  (net.http)  │     │  (workers)  │
                    │              │     └─────────────┘
                    │  ┌────────┐  │           │
                    │  │ SQLite │  │           │
                    │  │ (WAL)  │  │     ┌─────────────┐
                    │  └────────┘  │     │  Sandbox    │
                    └──────────────┘     │  (restricted│
                                         │   builtins) │
                                         └─────────────┘
```

## Security

Report vulnerabilities through GitHub's private advisories or the contact in
[SECURITY.md](SECURITY.md). Do not open a public issue for a suspected sandbox
escape or authentication bypass.

## License

MIT License - see [LICENSE](LICENSE) for details. Third-party browser libraries
bundled into the UI are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Author

Ricardo Robles Fernández - https://github.com/rroblf01/vlambda

