codex exec runs Codex without the interactive terminal interface. Give it a prompt or pipe in data, then save the answer for your next script step. This guide builds a deployment report with JSONL events, a schema-constrained result and an exit code based on real HTTP checks.

You will test two versions of a small quote API: one works, and one returns HTTP 200 from its health endpoint while the quote route fails. The complete example includes the collector, report schema and validation script.

Run Codex without the interactive interface

From a trusted Git repository, run:

codex exec --sandbox read-only \
  "Summarize this repository in three sentences. Do not change files."

Codex writes progress to stderr and its final answer to stdout. You can redirect that answer to a file. The official non-interactive guide covers this behavior and the supported automation patterns.

For a deployment report, we will supply the observations on stdin. A small Python collector makes the network requests. Codex explains the evidence, and a separate function checks the report against those observations.

Understand the three output files

These files have different roles:

--json changes stdout into an event stream. It does not make the whole stream a single report object. --output-schema describes the final answer, and -o saves that answer separately. This distinction prevents a common automation bug: trying to parse the entire event log with one JSON read.

Prepare the example

Use Python 3.10 or later and an authenticated Codex CLI. The Python files need no third-party packages. The shell commands below target Bash or Zsh on macOS or Linux.

codex --version
codex login status
mkdir codex-deployment-check
cd codex-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done

Read the downloaded files before executing them. Start the demo and keep it running:

python3 demo.py --port 8787

The application has two GET routes. /healthz returns status: ok. /api/quote?quantity=3 calculates a quote for three items at 1,200 cents each. The expected result is $36.00 (3,600 cents). The example uses integer cents to avoid rounding in the assertion.

Open another terminal in the same folder for the remaining commands.

Collect and inspect the HTTP evidence

python3 collect.py http://127.0.0.1:8787 > evidence.json

The collector records the URL, check time, HTTP status and whether each response matches its expected fields. It makes two bounded requests, rejects redirects and caps each response at 64 KiB. It sends expected values and booleans to the model, without copying arbitrary response text.

For your application, replace the demo paths and expected values in both collect.py and gate.py. Choose a route that exercises useful behavior: calculate a price, read a seeded database record or fetch an existing document. Match the response content as well as the status code.

The collector's exit code says whether it collected evidence. A failed application check still produces an evidence file, so Codex can explain the failure. The final gate determines the job's result.

Request a structured report

From a trusted Git repository containing the files, run:

codex exec --ignore-user-config --ephemeral \
  --sandbox read-only \
  --json \
  --output-schema report.schema.json \
  -o report.json \
  "Explain the evidence on stdin. Use no tools. Copy its verdict, list failed check names in failed_checks, and give a summary and next_step. Do not infer a root cause from HTTP status alone." \
  < evidence.json > events.jsonl 2> stderr.log

If you use only the new download folder, add --skip-git-repo-check. The complete wrapper does so in a temporary directory made for the report. Use that flag deliberately when no repository is needed.

--ignore-user-config skips the user's main Codex configuration file while retaining normal authentication. --ephemeral prevents saving the session rollout. The shell still saves the three explicit output files above. --sandbox read-only limits model-generated commands; the shell's redirects write the artifacts.

The schema requires verdict, failed_checks, summary and next_step, and disallows extra fields. The report should explain what the supplied checks establish. A response can suggest inspecting application logs after a 503, but the status code alone does not prove a database failure.

Parse the stream and the final answer separately

In our live test, Codex emitted these event types in order:

thread.started
turn.started
item.completed
turn.completed

The completed item was an agent message. These particular runs made no tool calls. Other tasks can produce more events, including command executions, tool calls and errors; do not require every successful run to have exactly four lines.

The wrapper reads each event and rejects turn.failed or error. It also requires turn.completed, a successful process exit and a final report that parses. Then it compares the report's verdict and failed-check names with the HTTP evidence.

A stream that ends early is an incomplete job. A report file left over from a previous run is also unsafe to reuse. The wrapper creates a new output directory and refuses to overwrite an existing run.

Run the complete workflow

python3 run.py codex http://127.0.0.1:8787 runs/healthy

This command collects fresh evidence, launches Codex with a 180-second process timeout, saves its output and validates the report. The wrapper exits 0 only when both application checks pass and the report agrees.

To reproduce the failure, start a second demo in another terminal:

python3 demo.py --port 8788 --broken

Then run the same workflow against that instance:

python3 run.py codex http://127.0.0.1:8788 runs/broken

The health route returns 200 and the quote route returns 503. Codex receives those observations and returns a failure report. The wrapper exits 1. The reporting process can complete successfully while the application check fails; your automation must use the wrapper's exit code for the application decision.

Results from the working example

We ran both scenarios with Codex CLI 0.156.1 and Python 3.12.10 on September 28, 2026. We also checked the Lizard CLI commands against version 4.0.8.

Both model calls completed and produced a report that matched the collected evidence. The broken-run report suggested reviewing logs at the recorded time. It did not claim that the health endpoint established full application health.

The local validation tests also reject a false success report and incomplete evidence. Run them without a model call:

python3 verify.py

This is a synthetic HTTP test on a local machine. It does not cover production traffic, public DNS, TLS, database migrations or every route. Add checks for the parts of your own deployment that matter.

Add Lizard service state and logs

For an application on Lizard, confirm the target before interpreting failures:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

Lizard CLI gives you machine-readable service information and a bounded log snapshot. The core guide matches the installed CLI version. Use it when you need more commands or flags, and use explicit project and service selectors in automation.

Run the adapted HTTP collector against the service's public URL. A container marked as running does not prove that a price lookup or database read works. Compare the HTTP failure time with the service logs to narrow the next investigation. Review and redact log content before sending it to a model.

If you need to deploy first, start with the coding-agent deployment guide. For apps with data dependencies, the Postgres MCP tutorial and Redis MCP tutorial explain scoped access for inspecting test data.

Use the result in automation

Keep three outcomes explicit: application passed, application failed, and report job failed. This wrapper uses 0, 1 and 2 respectively. A timeout, CLI authentication problem, invalid report or contradiction in the output produces code 2.

Store the evidence alongside the report. That lets a teammate verify the result without trusting a prose summary. Give scheduled runs distinct output paths, set a retention period and avoid storing credentials in artifacts.

On your own trusted machine, codex exec can reuse the saved CLI login. For GitHub Actions, follow the official Codex action guide for authentication and permission setup. Keep API credentials out of repository files and avoid exposing them to untrusted build steps. Review those runner-specific requirements before transferring a local command into CI.

Use fresh evidence for each independent check. codex exec resume can continue a conversation, but it is not needed for this one-shot report. The example's ephemeral mode makes each run independent.

Troubleshooting

Where to go next

Use this pattern for a focused deployment check, then add assertions for your application's real dependencies. Keep the checks small enough that a failed result points to a useful next step.

If your team uses Claude Code, the Claude Code headless guide shows the same HTTP checks with its result envelope. To run the application itself, use Lizard CLI and add the report after your deployment step.

Claude Code headless mode runs a prompt from your terminal with claude -p and exits when the task finishes. You can pipe in data, save the answer and call it from a script. This guide uses it to explain deployment checks: a health endpoint, a price quote and a report that your script can verify.

The example catches a common failure: /healthz returns HTTP 200 while a real application route returns 503. You will get a reproducible demo, a JSON report and a nonzero exit code when the application check fails.

Start with one non-interactive command

With Claude Code installed and signed in, run:

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

-p means print the result and exit. --tools "" disables the built-in tools for this question. Claude can answer from the prompt without reading your repository or running a shell command. The Claude Code CLI reference lists the available flags.

For a deployment check, give the model observations that your script has already collected. This makes each HTTP request and pass condition easy to inspect. It also keeps deployment credentials out of the model's input.

What you need

Use Python 3.10 or later, a current Claude Code installation and an authenticated account. The demo uses Python's standard library, so it has no Python packages to install. Run the shell examples in Bash or Zsh on macOS or Linux.

Check the installed CLI and its authentication state:

claude --version
claude auth status

If a request fails because the saved session has expired, run claude auth login and retry. A saved login can exist even when the next API request cannot refresh it.

For the optional hosted checks, install Lizard CLI and sign in to your own project. If you still need to deploy your application, follow Deploy from Claude Code first.

Download the example and start the demo

Create a new folder and download the six files. Read them before running them. The demo accepts GET requests and keeps no customer data.

mkdir claude-deployment-check
cd claude-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done
python3 demo.py --port 8787

Leave that terminal running. In another terminal, change to the same folder. The demo exposes /healthz and /api/quote?quantity=3. Each item costs 1,200 cents; a quote for three items must return currency: USD and total_cents: 3600.

These are demo routes. For your own application, edit the paths and expected fields in collect.py and gate.py. Choose a small operation a user actually needs: reading a seeded record, calculating a price or fetching a saved document. A route that only returns “OK” cannot verify those operations.

Collect evidence before asking Claude

python3 collect.py http://127.0.0.1:8787 > evidence.json

The collector makes two requests with a five-second timeout for each. It rejects redirects, invalid JSON and responses larger than 64 KiB. It checks both the HTTP status and the expected JSON fields. It records the time, expected values and check results; it does not copy arbitrary response text into the prompt.

That last choice matters when an endpoint contains user text. A support message or database row can contain instructions aimed at an agent. This example gives Claude a small set of measured fields to explain.

The collector exits successfully when it writes evidence, including evidence of a failed check. The final check script determines whether the job passes. Keep those two meanings separate in your automation.

Ask for a structured report

Run this from the folder containing the downloaded files:

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

The example uses --safe-mode to disable customizations such as hooks, plugins and MCP servers during this report task. It uses the existing account login. Check your installed version's help if it does not recognize the flag.

Claude's response has an outer result object. When you supply the schema, the report sits inside structured_output. The outer object also carries run metadata and an is_error field. A plain JSON response and a schema-constrained response serve different purposes; parse the field your command requested.

The schema asks for four fields:

The programmatic execution documentation describes these output formats. A valid JSON shape does not establish whether the explanation is correct, so the wrapper checks the report against the measured results.

Run the complete check

run.py collects fresh evidence, calls Claude with a 180-second process timeout, extracts the report and checks it. Give each run a new output directory:

python3 run.py claude http://127.0.0.1:8787 runs/healthy

The directory contains evidence.json, claude-result.json, report.json and stderr.log. Keep the raw result when debugging a failure; an authentication error can appear in the result on stdout.

The wrapper uses three exit codes:

Code 0 from the Claude process means the agent run completed. The wrapper makes the separate decision about the application. An invalid report cannot turn a failed HTTP check into a successful job.

Reproduce a failure that a health check misses

Start a second demo in another terminal:

python3 demo.py --port 8788 --broken

Then run:

python3 run.py claude http://127.0.0.1:8788 runs/broken

The second demo still answers /healthz with HTTP 200. Its quote route returns HTTP 503. The evidence therefore records fail, with quote as the failed check. With a valid Claude response, the wrapper exits 1.

You can also test the HTTP checks and validation logic without calling a model:

python3 verify.py

This checks the healthy and broken demos, then verifies that the gate rejects a false success report and incomplete evidence. It does not use Claude credits.

Apply the check to an application on Lizard

Choose the application URL from your project. Inspect the current project context and service state with Lizard CLI:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

lizard status shows the local folder's link. lizard ps reads the service state for the selected project. JSON logs return a bounded snapshot and exit; they do not keep following the service.

Use the service's public URL with the same checker after you adapt the two route assertions to your application. If you host the supplied demo itself, bind it to 0.0.0.0 and configure the service's port to match. The local examples bind to 127.0.0.1.

Read logs around the recorded check time when a route fails. An HTTP 503 alone cannot tell you whether the cause was a database connection, a dependency or application code. Review and redact any logs before adding them to a model prompt.

For applications that depend on stored data, add a test with a known record. The Postgres MCP guide explains scoped database access, and the Redis MCP guide covers restricted Redis reads. Use test data and credentials suited to the check.

Headless mode, authentication and unattended jobs

Headless mode describes how you run the command. It does not create an unattended login or remove tool permissions. For a scheduled job, prepare authentication on the runner and use an explicit timeout.

Claude also offers --bare, which skips much of the normal startup context. Its Anthropic authentication path uses ANTHROPIC_API_KEY or a configured API key helper; it does not read subscription OAuth credentials. Our account-login example therefore uses --safe-mode. Review the current documentation before moving the job to CI, where the authentication setup may differ.

For live progress, Claude supports --output-format stream-json --verbose. Each line is an event. Use plain json when you only need one final result, as this example does. Avoid resuming an old conversation for an independent deployment check; each run should use fresh observations.

Troubleshooting

Test scope and next step

On September 28, 2026, we ran the local HTTP and report-validation tests with Python 3.12.10. They covered healthy responses, a broken quote route, a false success report and missing evidence. We checked the command flags against Claude Code 2.1.259, Lizard CLI 4.0.8 and the official documentation. The Claude model response was not part of the completed tests; the report behavior above describes the documented output contract. These synthetic tests do not establish the health of a production application.

For the same pattern with JSONL events and a separate final report file, see Codex Exec deployment checks. To put your own app online, follow the Claude Code deployment guide, then add a check for the operation your users need most.

This guide gets that connection working with two small demo keys. You will read a string and a hash, inspect a TTL, and check that Redis rejects a write. You can start on your computer, then use the same approach with a dedicated Managed Redis instance in Lizard (lizard.build).

Tested September 27, 2026, Dubai time: Python 3.12.10, Redis 8.8.0, redis-mcp-server 0.5.1, MCP Python SDK 1.30.0 and redis-py 8.1.0. The downloadable test passed 14 checks against an isolated local Redis process through MCP over stdio. It did not test a hosted database, TLS or the Cursor and Claude Desktop interfaces. Those setup steps follow the linked product documentation. This guide was prepared with AI assistance; the test script and results are available below.

Choose the Redis MCP server that accesses data

The official Redis MCP server connects to a Redis endpoint. Its tools include string and hash reads, writes, key inspection and server information. Redis enforces the permissions of the credential you supply.

There are several Redis tools with MCP in their names:

We use the first one. A documentation connection will not give your agent access to your keys. Redis describes the distinction in its agent setup guide.

The MCP process runs on the same computer as your client and communicates through standard input and output, or stdio. It opens a separate network connection to Redis. This setup needs no public HTTP endpoint for MCP. A green connection indicator in the client only shows that the MCP process started; a tool call must still prove that Redis authentication and data access work.

1. Prepare a small Redis database

Use a dedicated learning instance with synthetic data. You need Python 3.10 or later, uv, and access to a Redis server. The local route also needs redis-server on your PATH.

Download these files into a new demo directory:

• requirements.txt: the pinned Python packages.

• setup.py: creates two keys and a restricted reader, then writes the MCP configuration.

• verify.py: starts its own local Redis process and tests the MCP connection.

• validation.json: the results from this guide's test run.

On macOS or Linux, create the Python environment:

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -r requirements.txt

In a separate terminal, start a temporary Redis instance:

redis-server --bind 127.0.0.1 --port 6391 --save "" --appendonly no

Leave that terminal running. This local instance has no persistence and listens only on loopback. Stop it with Ctrl+C when you finish. If port 6391 already belongs to another process, pick a free port and set ADMIN_REDIS_URL to match before running setup.

In your demo directory, run:

.venv/bin/python setup.py

The setup script connects to redis://127.0.0.1:6391/0 by default. It creates:

It also creates the user mcp_reader with a random password. It refuses to replace an existing user or demo keys, so a repeat run on the same instance stops with an explanation.

The script saves mcp.local.json with an absolute path to the installed MCP server. The file contains the reader password. Keep it private and add these paths to the demo project's .gitignore before committing anything:

.venv/
.env
mcp.local.json
.cursor/mcp.json
test-runs/

On Windows, use .venv\Scripts\python.exe for the Python commands. The script chooses the matching executable path for the generated config. This guide's automated run used macOS.

2. Understand the reader's permissions

The script applies this Redis ACL policy. This is Redis command syntax, with a placeholder password; the setup script generates the real password for you:

ACL SETUSER mcp_reader reset on >REPLACE_WITH_RANDOM_PASSWORD ~mcpdemo:* -@all +ping +get +hget +hgetall +type +ttl

The rules permit reads of known strings and hashes under mcpdemo:*, plus type and TTL checks. They deny writes, administration commands, pub/sub and key enumeration. The Redis ACL reference explains each rule.

A read-only prompt does not enforce read-only access. The database credential does. The MCP server can still advertise write tools; Redis should reject their execution for this user. Keep the client's approval prompts enabled as another check on which calls run.

Why the policy does not allow SCAN

An ACL key pattern restricts access to key values. It does not make SCAN return only the key names under that pattern. In our test, granting +scan let mcp_reader discover the name private:sentinel, even though it could not read that key's value. Revoking SCAN blocked enumeration again.

Start with known demo keys. If you later allow browsing on a separate instance that holds no unrelated data, use scan_keys in small iterations and follow the returned cursor until it becomes zero. COUNT is a work hint, not a hard result limit. See the SCAN reference. The tutorial's default policy deliberately rejects both scan_keys and scan_all_keys.

3. Add Redis MCP to Cursor or Claude Desktop

Open the generated mcp.local.json locally. It has this shape:

{
  "mcpServers": {
    "redis-demo": {
      "command": "/ABSOLUTE/PATH/redis-mcp-demo/.venv/bin/redis-mcp-server",
      "args": ["--host", "127.0.0.1", "--port", "6391", "--db", "0"],
      "env": {
        "REDIS_USERNAME": "mcp_reader",
        "REDIS_PWD": "YOUR_GENERATED_READER_PASSWORD"
      }
    }
  }
}

Use the actual generated file, not the placeholders above. Merge the redis-demo entry into your client's existing mcpServers object; keep any other servers already there.

Cursor: use .cursor/mcp.json in the demo project, or ~/.cursor/mcp.json for a user-level setup. Check the server in the client's MCP settings and enable it for the project. Cursor documents the file locations in its MCP integration guide.

Claude Desktop: merge the entry into claude_desktop_config.json. On macOS that file lives under ~/Library/Application Support/Claude/. Restart the app after saving. Follow the Redis client configuration guide for the current client steps.

This guide passes host, port and database as explicit arguments. In the tested 0.5.1 command-line entry point, default CLI values overwrite those settings if you supply only environment variables. Supplying REDIS_HOST alone can therefore leave the process trying 127.0.0.1. The username and password in the configuration above use the supported REDIS_USERNAME and REDIS_PWD variables.

4. Prove that the connection works

Ask your client to use the Redis tools explicitly. Approve the requested reads and inspect the tool output before relying on the model's summary.

Use redis-demo to get mcpdemo:status. Then use hgetall on
mcpdemo:session:42 and type on that same key. Report the raw
tool results and the remaining TTL. Do not change any data.

The expected results are:

• get returns ready.

• hgetall returns the two synthetic fields.

• type returns hash and a positive TTL below 3,600 seconds.

The official type tool includes TTL in its response. In our run it returned:

{
  "key": "mcpdemo:session:42",
  "type": "hash",
  "ttl": 3591
}

Your number will differ. A TTL of -2 means the key does not exist; -1 means it exists without expiry. If more than an hour has passed, the demo data may have expired. An authorised administrator can reseed the keys, or you can start a fresh local instance and run setup again.

Next, use the disposable demo to check the restriction:

Use redis-demo to try setting mcpdemo:status to changed once.
Report the exact tool result. Then read mcpdemo:status again.
Do not retry with other tools or credentials.

Our MCP call returned User mcp_reader has no permissions to run the 'set' command, and a separate read still returned ready. This verifies both the denial and the unchanged value. Some Redis MCP tools return an error as text, so inspect the response content even when the MCP call itself completes.

You can reproduce the underlying protocol checks without a model API key:

.venv/bin/python verify.py

The script starts its own Redis process on a free loopback port. It does not accept your database URL. It checks authentication, MCP startup, advertised tools, reads, TTL, blocked writes, unchanged data, another key prefix, missing keys, and the SCAN behaviour above. It stops only the process it created and saves validation.json beside the script.

5. Connect a dedicated Managed Redis instance

For a shared application database, create Managed Redis in the project dashboard and follow the connection guide. Use a separate learning instance for this exercise. Copy its connection URL into a private local .env file under the name ADMIN_REDIS_URL; never paste that administrator credential into an AI chat.

Load your own trusted file and run setup from the demo directory:

set -a
. ./.env
set +a
.venv/bin/python setup.py
unset ADMIN_REDIS_URL

The setup script uses that credential to create the synthetic keys and reader. Its generated MCP configuration contains only the new reader credential. It extracts host, port and database from the URL, and enables TLS certificate verification for rediss:// endpoints. Query parameters and custom certificate paths need a separate configuration; the script stops rather than guessing them.

The endpoint must be reachable from the computer running MCP. A plain redis:// URL has no transport encryption. Use a trusted private route or a verified TLS endpoint where available; changing the URL prefix does not add TLS support to a server. The current Managed Redis guide shows redis:// connections, so do not assume it supplies a public TLS endpoint.

Creating an ACL user also requires the provider to permit ACL SETUSER. If the provider denies it, use its supported user-management controls before connecting the agent. Do not put the administrator password into the MCP config as a workaround.

Redis ACL changes made at runtime need a persistence mechanism to survive a Redis restart. The current Managed Redis startup configuration does not declare an ACL file, so treat this demo user as temporary and verify it after restarts. Do not assume AOF persistence saves ACL users. Keep the tested permissions in your setup process and review the storage and recovery guide for the service's other limits.

Fix common Redis MCP connection errors

What to build after the connection works

Use this setup to inspect a synthetic session, check a cache entry's lifetime or debug an agent's saved context. Tool results can enter your model conversation, so choose which data the agent may read before you connect a real application.

If you want the application to save memories automatically, continue with AI agent memory with Redis. If your agent needs relational data, use the separate reader role in Postgres MCP.

Start with Managed Redis, connect the restricted reader, and verify one successful read and one denied write before expanding the tool set.

In this guide, a small Python assistant remembers that Alice prefers vegetarian meals. We stop one Python process, start another with a new session ID, and ask it to recall her preference. Bob gets a separate profile. A forget command removes Alice's live Redis records.

You can run the example locally, then connect the same code to Managed Redis in Lizard (lizard.build). It uses standard Redis Hash and List commands, so this walkthrough needs no vector index, RedisJSON or agent framework.

Tested on September 25, 2026: Python 3.12.10, Redis 8.8.0, redis-py==5.2.1 and four live calls to openai/gpt-4.1-mini through OpenRouter. All 16 checks passed. The test covered separate application processes and sessions on a local Redis instance. It did not cover a hosted instance, concurrent requests or recovery from a Redis crash.

What should an AI agent remember?

Start with two kinds of data. They need different keys and retention rules.

The profile belongs to the user, so a new session can read it. Conversation history belongs to one user and one session. Starting a second session does not copy the first session's transcript.

This distinction matters when the agent answers “What do you know about me?” A recent message can disappear from a bounded history list. A saved preference has its own retention period. Neither has to stay in the model's context forever.

Redis also offers a separate Redis Agent Memory service. This tutorial builds a small memory layer in application code using a Redis connection. It does not use that service or its automatic extraction features.

1. Set up the demo

You need Python 3.10 or later, a disposable Redis instance and an OpenRouter API key. Use invented preferences while testing: the saved profile and selected chat messages go to the model provider on each call.

Download the complete, tested program and install its one Python dependency:

mkdir redis-memory-demo
cd redis-memory-demo
python3 -m venv .venv
. .venv/bin/activate
python -m pip install redis==5.2.1
curl -fsSLo memory_agent.py \
  https://lizard.build/blog-examples/redis-agent-memory/memory_agent.py

For a local test, run Redis in a separate terminal. This command binds it to loopback on port 6387; keep that terminal running:

redis-server --bind 127.0.0.1 --port 6387 --save "" --appendonly no

This local Redis process is deliberately disposable. Its data remains available when the Python application exits, but stopping Redis loses that data. The test below restarts the application, not the database.

Create a private .env file in the demo directory using your editor:

REDIS_URL=redis://127.0.0.1:6387/0
OPENROUTER_API_KEY=replace-with-your-key
OPENROUTER_MODEL=openai/gpt-4.1-mini

Keep .env out of Git. Restrict access and load it into the current shell:

chmod 600 .env
set -a
. ./.env
set +a

The example calls the OpenRouter Chat Completions API. Redis handles the same memory reads and writes if you replace the model call with another provider.

2. Give each user and session their own keys

The program creates keys like these:

agentmem:v1:{alice}:profile
agentmem:v1:{alice}:session:session-1
agentmem:v1:{alice}:session:session-2
agentmem:v1:{bob}:profile

The version prefix gives future data formats a separate namespace. The user ID separates profiles. The session ID separates conversations. The braces are a Redis hash tag; they keep one user's keys in the same hash slot if you later use Redis Cluster. This guide tests a single Redis instance.

The demo validates IDs before building keys. In a web application, derive the user ID from the authenticated server session. Do not accept another user's ID from a request body and treat it as proof of identity. Redis key names alone do not enforce who can access a user's data.

3. Save an explicit preference

Save Alice's choice:

python memory_agent.py remember --user alice --preference vegetarian

The command prints Preference saved. Internally, it writes a field to a Redis Hash and sets the profile's expiry in a transaction:

with client.pipeline(transaction=True) as tx:
    tx.hset(profile, mapping={"dietary_preference": preference})
    tx.expire(profile, 30 * 24 * 60 * 60)
    tx.execute()

The only allowed values are vegetarian, vegan and no_preference. That small schema makes the example easy to inspect. The model cannot write arbitrary claims into the profile. In a real product, a “Remember this” control can make the same validated write after the user confirms it.

This guide does not infer preferences from every chat message. Changing or correcting a preference uses the same explicit command, which overwrites that field and renews its 30-day TTL.

4. Load memory before calling the model

Ask the assistant to recall the saved choice:

python memory_agent.py chat --user alice --session session-1 \
  --message "What dietary preference have I saved?"

In our test, the model replied:

Your saved dietary preference is vegetarian.

For each call, the application reads the user's profile and the current session's recent messages. It builds the model request in this order:

1. Instructions that define the assistant's task.

2. A data message containing the allowed saved preference.

3. This session's recent user and assistant messages.

4. The new user question.

The model has no direct Redis credentials or general database tool. It only receives the selected context. After a successful reply, the app stores the new user and assistant messages together:

with client.pipeline(transaction=True) as tx:
    tx.rpush(history, *rows)
    tx.ltrim(history, -20, -1)
    tx.expire(history, 24 * 60 * 60)
    tx.execute()

Each turn contributes two messages, so the list keeps the last ten complete turns. The app also caps each message at 2,000 characters. A message count alone would not bound context size if one message could contain an entire book.

In this example, reading memory does not renew its expiry. Profile writes renew the profile TTL; completed chat turns renew the session TTL. See the Redis EXPIRE reference for how expiry interacts with updates.

5. Start a new process and a new session

Each CLI command starts and exits its own Python process. Run a second chat command with a different session ID:

python memory_agent.py chat --user alice --session session-2 \
  --message "What dietary preference have I saved?"

The model again returned Your saved dietary preference is vegetarian. The new session began without the first conversation's messages. Its request contained the shared user profile, which was enough to answer.

Inspect the records the application reads:

python memory_agent.py inspect --user alice --session session-2

You should see a profile with dietary_preference and a history with that session's user question and assistant answer. The model has not learned a new weight or gained permanent internal memory. The application supplies the stored context on each request.

6. Check user separation and forgetting

First, inspect another user's context:

python memory_agent.py inspect --user bob --session session-1

For a fresh Bob profile, the result is:

{
  "profile": {},
  "history": []
}

Asking Bob's assistant the same preference question produced Your dietary preference is unknown. in our test. The empty context is the deterministic isolation check; model wording can vary.

Next, stop any requests for Alice and remove her live Redis memory:

python memory_agent.py forget-user --user alice
python memory_agent.py inspect --user alice --session session-1
python memory_agent.py inspect --user alice --session session-2

Both inspections should return empty profiles and histories. The command scans only Alice's validated key prefix and unlinks matching keys. It leaves Bob's keys alone.

For a deployed app, block new writes for that user while deletion runs. Otherwise, a reply that finishes during the scan could recreate a session. Deleting Redis keys also does not delete provider logs, backups or records in another database; those stores need their own retention and deletion rules.

What we tested

The verification script starts a new Redis process on an available loopback port. It never connects to an existing database. Its saved results record the versions, scope and four model replies.

The harness ran 16 checks in total. These results show that the example's reads and writes work as described. They do not establish a production availability or data recovery guarantee.

Connect the example to Managed Redis

After the local test, create a separate Redis instance for your project. In a linked Lizard project, run:

lizard add redis

For a deployed service named api, set the connection reference and redeploy:

lizard secrets set REDIS_URL='${{redis.REDIS_URL}}' --service api
lizard redeploy --service api

These commands assume the service already exists and has its model API key configured. They connect that service to Redis; the CLI demo itself is not an HTTP server. Follow the Managed Redis connection guide for environment variables and access from your computer.

You can inspect the demo's keys in the Redis browser in the dashboard. Keep Redis credentials on the server, and use a private connection or verified TLS when your provider supplies it. A plain redis:// URL does not add transport encryption.

Decide which memories must survive data loss

Memory surviving an application restart does not mean it survives every Redis failure. Expiry, key eviction, persistence settings and backups all matter.

Managed Redis currently documents an allkeys-lru eviction policy: memory pressure can remove any key, including a profile whose TTL has not elapsed. For preferences you cannot afford to lose, keep the source record in Managed Postgres and use Redis for recent context or a reloadable copy. Review the storage and recovery guide before choosing a retention policy.

Before you put this behind a web API

The CLI keeps the example small. A shared application also needs:

• Authentication and ownership checks. Derive user IDs on the server and check that each session belongs to that user.

• One active turn per session. Queue or lock the full read → model call → write sequence. The final Redis transaction alone does not stop two model calls from reading the same old context.

• A memory size budget. Bound profile fields, message size, history length and the number of sessions. Monitor Redis memory and evictions.

• A Redis failure policy. Fail the request clearly or offer an explicitly stateless mode. Never claim a preference was saved when the write failed.

• Separate authority from remembered text. A saved message can contain hostile instructions. Keep permissions and tool decisions in application code; a system prompt is not an access-control boundary.

Common questions

Do I need a vector database for AI agent memory?

You can load a known user's explicit preferences and recent messages by key, as this example does. Vector search becomes useful when the application must find relevant facts in a much larger set of memories. That adds embeddings, index configuration and retrieval tests.

Does Redis make an agent remember forever?

Retention depends on TTLs, eviction, persistence and your application's writes. This example deliberately expires data. Keep durable records elsewhere when losing them would break the product.

Is this RAG or a semantic cache?

This example retrieves one user's saved context. RAG commonly retrieves relevant source material to help answer a question. A semantic cache reuses a prior answer for a similar query. They can share Redis infrastructure, but they need different data models and tests.

Can I use LangGraph later?

Yes. LangGraph offers checkpoints for conversation state and stores for memory across threads. Its Redis integration has its own requirements; check the LangGraph Redis package documentation before replacing this simple client with a framework backend.

Give your agent a memory you can inspect

Start with one explicit fact, a separate session history and a test that crosses a process boundary. Add expiry, ownership checks and a way to forget before you add automatic extraction or vector search.

Create Managed Redis for the application's shared context. If your agent also needs to query structured project data, the Postgres MCP guide covers that connection with a separate database reader role.

This guide connects Cursor to a sample database using Postgres MCP Pro, a separate database role and restricted access mode. The end result is easy to check: the agent should find two active projects with a combined monthly budget of $68. It should fail if it tries to change those rows.

You can create the database with Managed Postgres on Lizard (lizard.build). The MCP process runs on your computer. The same SQL setup also works with a local PostgreSQL instance you own.

How Postgres MCP connects to your database

The agent sends a tool call to the MCP server. The server connects to PostgreSQL, runs the query and returns the result. PostgreSQL checks the permissions of the connection's database role.

We use Postgres MCP Pro, an independent open-source project. It exposes tools for listing schemas, reading table details and executing SQL. Lizard supplies the database in this setup.

The local connection between Cursor and the MCP process uses stdio. Your computer must be able to reach the database endpoint. Query results can enter your AI provider's context, so this walkthrough uses invented project names and budgets.

What you need

• A new PostgreSQL instance or a separate disposable database, with an owner account that can create a database and a role.

• psql on your computer.

• uv, which runs the pinned Python package.

• Cursor with custom MCP servers enabled.

We tested the SQL and MCP calls with PostgreSQL 14.20, Python 3.12.10, postgres-mcp==0.3.0 and mcp==1.30.0. The result table below records the scope of those checks.

1. Create a sample Postgres database

In a new Lizard project, add Managed Postgres from the dashboard. If you already use Lizard CLI and have linked the new project, run:

lizard add postgres

The dashboard provides the host, port, database and credentials. Follow the Managed Postgres connection guide to connect with psql. Use the owner account for this setup; the agent will receive a different account.

In psql, create and switch to a fresh database:

CREATE DATABASE mcp_demo;
\connect mcp_demo

\connect is a psql command. If you use a SQL editor, select mcp_demo before running the next block. If the database name already exists, choose another name and update the later examples.

Create one table with three rows:

CREATE SCHEMA demo;

CREATE TABLE demo.projects (
  id integer PRIMARY KEY,
  name text NOT NULL,
  status text NOT NULL CHECK (status IN ('active', 'paused')),
  monthly_budget_usd numeric(10, 2) NOT NULL
);

INSERT INTO demo.projects VALUES
  (1, 'Atlas', 'active', 49.00),
  (2, 'Beacon', 'active', 19.00),
  (3, 'Cedar', 'paused', 0.00);

These amounts belong to the sample data. They are not Lizard prices.

2. Give the agent a role that can read the sample table

Create a login with no administrative privileges:

CREATE ROLE mcp_reader LOGIN
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;

Then run this psql command to set its password without putting the password in SQL history:

\password mcp_reader

The following grants are for the fresh mcp_demo database. The PUBLIC revocations affect other roles that use that database, so do not paste this block into an existing shared application database.

REVOKE ALL ON DATABASE mcp_demo FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

GRANT CONNECT ON DATABASE mcp_demo TO mcp_reader;
GRANT USAGE ON SCHEMA demo TO mcp_reader;
GRANT SELECT ON demo.projects TO mcp_reader;

ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET default_transaction_read_only = on;
ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET statement_timeout = '5s';

This grants access to one table. A table you create later needs its own grant. PostgreSQL may still expose object names through system catalogs; table permissions control access to the rows. See PostgreSQL's GRANT reference.

The read-only default helps avoid mistakes, but a client can change that setting. The table grants are what prevent this role from writing to demo.projects. We checked that an update still fails after turning the default off.

3. Save the reader connection outside your source code

Build a connection URL using the new role and the mcp_demo database. Keep the host, port and required TLS settings from your provider's connection instructions. Percent-encode special characters in the password when putting it in a URL; PostgreSQL documents the connection URI format.

For a hosted endpoint that requires TLS, the shape is:

postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

sslmode=require requires encryption. If your provider supplies a CA certificate and hostname for full certificate checks, use its verify-full configuration. A certificate error needs a matching host and trust configuration; do not solve it by disabling TLS on a hosted connection.

Add .env.mcp to your project's .gitignore, then create that file at the project root:

DATABASE_URI=postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

Replace every placeholder with your reader connection values. The name is DATABASE_URI: that is what Postgres MCP Pro expects. Lizard's application connection variable is named DATABASE_URL; passing that name alone will not configure this MCP server.

Keep the owner connection out of this file. On macOS or Linux, restrict access to the reader file:

chmod 600 .env.mcp

4. Configure Postgres MCP in Cursor

Create .cursor/mcp.json in the same project. If the file already contains other servers, add postgres-demo inside its existing mcpServers object.

{
  "mcpServers": {
    "postgres-demo": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--with", "mcp==1.30.0",
        "--from", "postgres-mcp==0.3.0",
        "postgres-mcp", "--access-mode=restricted"
      ],
      "envFile": "${workspaceFolder}/.env.mcp"
    }
  }
}

Cursor supports project MCP configuration and envFile for local stdio servers. See its MCP configuration reference. If Cursor cannot find uvx, replace the command with its full installed path.

The two version pins matter. During our check, installing postgres-mcp==0.3.0 without an MCP SDK constraint selected mcp==2.2.0. The server then failed to import mcp.server.fastmcp. With mcp==1.30.0, it started and completed the tests below.

To check the package launch before opening a database connection, run:

uvx --python 3.12 --with 'mcp==1.30.0' \
  --from 'postgres-mcp==0.3.0' postgres-mcp --help

Enable or restart postgres-demo in Cursor's MCP settings. Leave tool approval enabled while checking the setup, and inspect the SQL arguments before allowing a call.

5. Verify the tools and the answer

Start with a schema question:

Use postgres-demo to inspect the demo schema. List its tables and the columns
of demo.projects. Show the tool results. Do not change the database.

The server should expose list_schemas, list_objects, get_object_details and execute_sql. Confirm that the agent calls the tools and reports id, name, status and monthly_budget_usd from the table.

Then ask:

Using demo.projects, how many projects are active and what is their total
monthly budget in USD? Show the SQL and the database result.

A query for that answer is:

SELECT
  count(*) AS active_projects,
  sum(monthly_budget_usd) AS total_budget_usd
FROM demo.projects
WHERE status = 'active';

The expected values are:

Finally, check the restriction on this sample table. The WHERE false condition ensures the query has no matching rows:

Use execute_sql to run exactly:
UPDATE demo.projects SET name = name WHERE false;
Report the tool response. Do not retry with another tool or connection.

In our test, restricted mode returned Error: Error validating query. A separate direct connection using mcp_reader returned permission denied for table projects even after we disabled its read-only default. The MCP check and database grants each rejected the operation.

What we tested

On 24 September 2026, we ran the sample SQL and real MCP calls against a new local PostgreSQL 14.20 instance with synthetic data. We used Python 3.12.10, Postgres MCP Pro 0.3.0 and MCP SDK 1.30.0.

These checks cover the SQL permissions and MCP protocol. We did not run the Cursor UI flow or deploy a new Lizard database for this test. Follow the checks above against your own endpoint; a connected MCP indicator alone does not prove the database tools work.

Fix common Postgres MCP connection errors

Do you need PostgreSQL extensions?

The schema and data queries in this guide need no extra extension. Postgres MCP Pro also offers performance tools that have different requirements.

Its top-query analysis uses pg_stat_statements. Hypothetical index analysis uses hypopg. Availability, server configuration and role permissions all matter; creating an extension may require an owner action or a server change. Check the project's extension requirements before using those tools.

Start with the schema and SELECT checks. An extension-related failure in a tuning tool does not, by itself, mean the basic MCP connection is broken.

FAQ

Is Postgres MCP the same as Lizard MCP?

No. This example uses Postgres MCP Pro to query a PostgreSQL database. Managed Postgres provides that database. The connector is a separate project.

Can I use a different AI agent?

Yes, if its client supports local MCP servers over stdio. Use the same pinned process, reader credentials and restricted mode, then follow that client's configuration format. The JSON above is for Cursor.

Does restricted mode replace database permissions?

Use both. Restricted mode checks queries in the MCP server. PostgreSQL's grants limit what the connection role can do even through another client. Keep the owner account for migrations and administration.

Will it create tables or run migrations for me?

This setup grants the reader access to the sample table. It cannot create or change your application's schema. Run reviewed migrations with your normal application deployment process.

Connect the database to your app next

Once the agent can inspect the sample schema and return the expected answer, you have a working basis for database questions during development. Keep the agent's reader credentials separate from your application's credentials as you add tables.

Create Managed Postgres for your project, follow the database connection guide, or continue with the Cursor app deployment example. For deploying an MCP service shared by several clients, see the separate remote MCP server guide.

Originally published on Lizard.

This comparison comes from Lizard. We checked the linked product documentation and billing terms on 9 September 2026. The calculations below are examples with stated inputs, not performance tests or customer savings figures.

Start with the runtime you need

A Dockerfile describes how to package an application. It does not tell you how a hosting service schedules, stops or bills that application.

Vercel now supports container images for Functions. Its Services documentation says Services use Function compute and inherit Function limits. Check the current duration, filesystem and connection limits for the specific feature and plan you intend to use.

For a conventional queue consumer, a process that keeps a connection open, or a scheduler that runs outside HTTP requests, test that lifecycle before moving. A managed queue or workflow can solve the same business problem, but it can also require changes to your code.

These are starting points for a trial. None establishes a universal winner. Our PaaS comparison covers the broader choice.

Where Lizard fits

Lizard runs web services and workers, offers Managed Postgres, Managed Redis and Managed Object Storage, and exposes deployment and operations through the Lizard CLI.

That fits a backend with a familiar process model: start the API, run the worker separately, and give each service its own configuration. A coding agent can read structured deployment output, inspect logs and run a specific command inside a service. It still needs to check the result; a successful build alone does not prove that logins, jobs and database writes work.

Provisioning a database and connecting your application are separate steps. Your application must read the connection variable you configure. Keep app data in the database or an attached Persistent Volume, according to the service's needs. A writable container filesystem by itself is not a backup or a promise of durability across deployments.

When Vercel is a better fit

Stay with Vercel when your team depends on its preview workflow, frontend tooling or managed request lifecycle and those features already meet your needs. Replacing a working deployment system has a cost even if another provider advertises a lower CPU rate.

An application with little traffic can also benefit from compute that does not remain active between requests. A running Lizard service can still consume memory while waiting for work. Compare the actual workload and latency requirements, including whether you are willing to accept cold starts.

You can keep the frontend on Vercel and move only the worker or API. In that design, include cross-provider data transfer, authentication and request latency in the test.

Compare bills after fees, credits and allowances

The monthly total depends on more than runtime CPU. Record the plan, billing period, region, seats, database, storage, requests, traffic and builds. Apply each allowance to its own meter and each credit once.

Sources: Lizard pricing, Vercel Pro terms and Vercel build billing. CDN transfer, origin transfer and Function invocations are distinct Vercel meters. Check the terms your account uses before reusing an older estimate.

Hosted build costs: Lizard and Vercel

Lizard charges for builds. Include those charges when comparing deployment costs.

For a paid Vercel Standard machine with 4 vCPUs, 200 builds at exactly 3 billable minutes each use 2,400 CPU-minutes. At $0.0035 per CPU-minute, that is $8.40 before plan credit and tax, or $0.042 per build. Vercel build rates, checked 15 September 2026.

Vercel credits can cover some or all of this usage, so $8.40 is not necessarily an extra payment on top of the plan. Basic builds are included on eligible Vercel Hobby projects. This is a Vercel build-cost example, not a build-speed comparison or the full monthly bill.

Where no subscription lowers the bill

Lizard charges 200 GB of outgoing traffic at 200 × $0.045 = $9. There is no bundled traffic allowance to subtract. Vercel Pro includes a CDN allowance, so compare that meter separately from Function and origin traffic.

For an illustrative small app running for 720 hours, assume average measured use of 0.01 vCPU and 0.1 GB of memory, plus 10 GB of outgoing traffic. No database, retained storage or paid add-ons are included. At Lizard rates:

Lizard costs less for this small-app example than the $20 Vercel Pro monthly minimum, provided Lizard top-up fees allocated to this usage stay below the $18.47 difference. Three deploying seats raise that Pro minimum to $60. These are paid-plan comparisons before tax and trial credits; Vercel Hobby can cost $0 for an eligible project. We do not assume identical resource consumption across the two runtimes. Vercel Pro terms, checked 15 September 2026.

Purchased credits pay for usage and do not expire. A top-up can exceed this month’s usage because the unused balance stays available; the top-up screen shows its fee and total charge.

This example shows a specific price advantage from having no monthly minimum. For a larger app, compare measured resource use, included CDN traffic and required features on both hosts before estimating savings.

Move one service before moving the whole app

1. List Vercel-specific dependencies: request handlers, image processing, cache behaviour, scheduled work, storage and environment variables.
2. Choose an API or worker that can run independently. Give it a production start command and a health endpoint where appropriate.
3. Deploy a test copy and connect it to a separate test database. Configure credentials through service settings.
4. Test authentication, retries, timeouts, file handling and restarts with representative traffic.
5. Measure cost and latency, then plan the database and domain cutover. Keep a rollback path until you have checked writes on the new deployment.

For a GitHub repository, start with the Git deployment guide. For a local project, use the upload deployment guide. The CLI configuration reference explains how to keep deployment settings repeatable.

FAQ

Can Vercel run a Dockerfile? Yes. Vercel documents container-image support for Functions. Check the runtime limits as well as the packaging support before treating it as a replacement for an always-running backend.

Is Railway billed as a flat server tier? No. Railway meters resource consumption and applies the paid plan's subscription fee toward usage. Its billing model differs from buying a fixed instance size. See the Railway pricing documentation.

Can I keep Vercel for the frontend? Yes. A separate API or worker can run elsewhere. Test cross-origin requests, cookie settings, authentication and network costs as part of that split.

Which option is cheapest? For the small app priced above, Lizard’s resource cost is about $1.53 plus payment fees, below Vercel Pro’s $20 monthly minimum. Lizard also has no seat fee. Vercel Hobby may be free for an eligible project, and included CDN traffic can change the result for a larger app.

What should an AI coding agent verify after deployment? The live URL, health checks, logs and a real user flow. For a backend, also check database writes, worker execution and recovery after a restart. The Claude Code deployment guide shows that workflow.

Originally published at Lizard (lizard.build).

The useful result is a working user flow at a live URL, not just a command that exits successfully. This guide checks the Lizard CLI and linked documentation as of 9 September 2026.

Give the agent the right context

Start with a repository that builds and has a production start command. Identify the workspace and project that should own it, whether it needs a database or worker, and whether the deploy creates a test copy or changes an existing service.

Install the CLI and read its version-matched instructions:

npm install -g @lizard-build/cli
lizard skills get core --json
lizard status --json

If authentication is needed, use lizard login and finish the browser sign-in. For the reusable agent instructions, follow the Lizard Skill repository. Claude Code's own overview describes how it works with a codebase and tools.

The agent should inspect existing configuration before adding anything. A runtime version, Dockerfile or start command already in the project is better evidence than a command guessed from the framework name.

A prompt that defines the deployment task

Give the agent a bounded instruction such as:

Deploy this repository to the existing Lizard project my-project as a test service. Read the current Lizard CLI guide and inspect the build and start commands first. Use the GitHub source if the repository has an accessible GitHub remote. Configure the services this app actually needs. Verify the live URL, logs and one real application flow. Report the deployed revision and any check that failed.

Replace the project and environment with the intended target. State explicitly when a production service or domain should change. The agent should not infer a production database migration from a request to publish a test copy.

Choose Git deployment or source upload

Use the repository's GitHub integration when you want later commits to trigger deployments. The GitHub deployment guide covers connection and service setup. Check the tracked branch and root directory for a monorepo.

For a local project without a suitable GitHub remote, source upload is available. After selecting the right workspace, a new example project and service can use:

lizard init --name my-project
lizard add --service api
lizard up --service api

These names are examples. For an existing project, confirm the current link with lizard status --json and select the existing service. Do not create another project or switch a Git-backed service to upload merely to avoid reading its settings.

Lizard performs the hosted build. Depending on the project and service configuration, it can use the repository's Dockerfile or generate one through the supported build path. Read the deployment docs and keep the settings in the configuration reference repeatable.

Connect the database deliberately

Creating Managed Postgres does not prove the application can reach it. The application must read the connection variable you set. For a project with a service named api and its first PostgreSQL add-on named postgres, the reference is:

lizard add postgres
lizard secrets set 'DATABASE_URL=${{postgres.DATABASE_URL}}' --service api

Use the add-on's actual name if it differs. Configure each consumer service, including workers, with the variables it needs. Run migrations as a controlled release step and confirm an application read and write against the intended database. See variable references and Managed Postgres.

For uploads, choose storage that survives the lifecycle your app needs. For a worker, check that it can reach the broker and handle restarts. Avoid treating the successful creation of resources as a completed application setup.

Check the result from the outside

Use structured output for diagnostics:

lizard status --json
lizard logs --service api --json
lizard logs --service api --build --json
lizard metrics --service api --json

Then fetch the live URL and exercise a real flow. For a small API, that might be authentication followed by a write and read. For a frontend, check a route reached directly by URL as well as through client-side navigation.

If deployment fails, use the reported error to choose the next check:

An agent should report an unresolved error rather than declare success from the build log. The Python hosting guide gives examples of start-command problems.

Understand the cost of the workflow

Your coding subscription and hosting bill pay for different parts of the work. Lizard uses pay as you go with no monthly subscription. Its pricing page lists resource rates and payment terms. A test service, database or sandbox can continue consuming resources after the coding session ends.

Set resource limits and review use. Stop or remove temporary resources when they are no longer needed through your normal approval process. Do not assume that closing Claude Code stops an application that has already deployed.

FAQ

Does Claude Code host the app? The deployment target does. Claude Code uses tools to prepare and deploy the code; the hosting provider runs the resulting application.

Can I deploy an existing GitHub repository? Yes, if Lizard can access it. Configure the repository, branch and service through the Git deployment workflow, then verify the deployed revision.

Do databases connect automatically? Provision the database, configure the variable the application reads, and test the connection. Those are separate checks.

Can the same workflow work with another coding agent? An agent that can use the required tools can follow the same deployment checks. Read its own permission and tool setup rather than assuming every environment behaves like Claude Code.

How do I know the deployment is complete? Confirm the live URL, expected revision, healthy process and meaningful application behaviour. A successful build alone is not enough.

Originally published at Lizard (lizard.build).

This comparison comes from Lizard. We checked the linked documentation on 9 September 2026. Start with architecture and migration effort, then compare the bill.

Firebase is more than a database

An app may use Firestore, Realtime Database, Authentication, Storage, Functions, Hosting and messaging in different combinations. Each has its own API and cost model. Firebase pricing lists those products separately.

Exporting documents solves only part of a migration. The client may depend on realtime listeners, offline behaviour and security rules that the new system expresses differently. Authentication also includes identity providers, account recovery and sessions, not just a users table.

Make a list of SDK calls in your application. Use it to define the replacement contract before picking a vendor.

A shortlist by backend model

Read the primary product documentation for Supabase, Appwrite, Convex, Nhost and Amplify before treating a feature label as equivalent behaviour.

When PostgreSQL is the reason to move

A relational database can fit data that benefits from joins, transactions and explicit constraints. It also changes how you model and query documents that were designed for Firestore.

Start with the queries your app must answer. Map collections, nested values and identifiers to a schema, then check reads and writes with real data. Do not assume a mechanical conversion of every document produces a useful relational model.

If you choose your own API, Managed Postgres provides the database on Lizard. Your application still implements its endpoints and access checks. Supabase or Nhost may be a closer fit when you want an integrated backend API rather than building one yourself.

When self-hosting is the reason to move

Self-hosting gives you control over deployment and data placement. It also makes backups, upgrades, monitoring and recovery part of your operating plan.

PocketBase combines an embedded SQLite database with auth, file handling and realtime features. Its documentation warns that backward compatibility is not guaranteed before version 1.0 and advises caution for production-critical applications. Evaluate that stated limit against your project rather than presenting a small binary as an automatic production replacement. PocketBase documentation.

For any self-hosted backend, test restoration from backup and the upgrade path before depending on it. A process that starts successfully has not yet demonstrated data recovery.

Compare the complete cost model

Firestore billing can include document operations, storage and network use. Another product may charge by database compute, users, function usage or a base plan. Those units measure different things. Firestore billing documentation.

Record the same workload for each option: active users, reads, writes, stored data, file downloads, function execution and required environments. Add the plan you need for backups or other essential features. Use Firebase, Supabase, Appwrite and Lizard pricing as applicable.

Avoid calculating savings by comparing a database's entry plan with the whole Firebase bill. Also include development work: replacing client SDK calls and security rules can cost more than a small monthly hosting difference.

A migration plan that tests permissions

1. Inventory the Firebase products, SDK calls, security rules and identity providers in use.
2. Design the replacement data model and the access rules for each user role.
3. Import a test dataset. Check counts, identifiers, timestamps and representative application queries.
4. Test access as an anonymous user, a normal user and an administrator. Include denied reads and writes.
5. Test sign-in, sign-out, password recovery, file access and realtime updates where used.
6. Plan the final write transition, client release and rollback. Old mobile or browser clients may continue calling the old API.

On Lizard, a custom backend can use Managed Redis where appropriate and Managed Object Storage for files. Storage access policy must match the sensitivity of those files; do not assume a newly provisioned bucket is private.

FAQ

Is Lizard a direct Firebase replacement? Lizard can host your backend and data services. It does not automatically supply the Firebase client API, auth flows or security rules. Choose it when you want to run that server-side application.

Which alternative is closest to Firebase? It depends on which Firebase products you use. Compare actual APIs, auth, file access and realtime behaviour rather than selecting by a feature count.

Can I keep Firebase Authentication and move the database? You can design a backend that verifies the existing identity tokens. Check token verification and authorization carefully; accepting an identity is not the same as granting access to every record.

Will PostgreSQL remove all usage charges? No. The host still charges under its own plan for compute, storage, traffic or other services. The meter changes; the need to estimate the workload remains.

What is the most important migration test? Confirm that users can access exactly the records and files they should, and no others. Data import success alone does not prove correct permissions.

Originally published at Lizard (lizard.build).

Lizard publishes this guide. We checked the linked framework and provider documentation on 9 September 2026. The examples use explicit module names that you must adapt to your project.

Choose the runtime before the host

The development server is for development. See the official Django deployment guide, Flask production guide and FastAPI worker guidance.

Python hosting options by need

Use the PaaS comparison for the wider hosting decision. A Python badge in a feature table is not enough to confirm worker or database support.

Free Python hosting needs a workload limit

A free plan may restrict outbound requests, sleep an inactive web process, limit task execution or include only a trial credit. Those terms can be fine for a demonstration and unsuitable for a webhook receiver or queue worker.

Check Render's free-service rules and PythonAnywhere's free-account features. For Cloud Run, the pricing page describes free usage alongside billable resources. A database, image registry or network usage may remain outside the allowance you are looking at.

Test the first request after a quiet period and confirm whether scheduled or background work still runs. Describe the free option in terms of those limits, not as unlimited hosting.

Build and start commands

For a project that uses requirements.txt, install its pinned dependencies with:

python -m pip install -r requirements.txt

Use the package manager and lockfile already in your repository if it uses uv, Poetry or another tool. Include the production server in the dependencies. Do not rely on a package installed only on your laptop.

For Django, where myproject/wsgi.py defines the application:

gunicorn myproject.wsgi:application --bind "0.0.0.0:${PORT:-3000}"

For Flask, where app.py exports app:

gunicorn app:app --bind "0.0.0.0:${PORT:-3000}"

For FastAPI, where main.py exports app:

uvicorn main:app --host 0.0.0.0 --port "${PORT:-3000}"

These commands expect a shell to expand the port variable. A JSON-array Docker CMD does not expand it automatically. Either use the runtime's documented variable support, a shell wrapper, or a small program that reads the environment.

Set worker counts from measurements and available memory. More processes can use more memory and database connections; adding workers is not a substitute for checking a slow query or blocking task.

A minimal FastAPI container

For an application with main.py and a locked requirements.txt containing FastAPI and Uvicorn, this Dockerfile starts one server process:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN useradd --create-home appuser
USER appuser
EXPOSE 3000
CMD ["sh", "-c", "exec uvicorn main:app --host 0.0.0.0 --port ${PORT:-3000}"]

Choose a Python version compatible with your project. Put .env, local virtual environments, caches and Git data in .dockerignore. This example does not install extra operating-system packages; add only those your dependencies need.

On Lizard, you can bring a Dockerfile or use the source-build path. The deployment guide explains the options. Your app should expose a small health endpoint, and you should also test an endpoint that exercises its real dependencies.

A FastAPI deployment checked on Lizard

Our public FastAPI example has a dated deployment record from 9 September 2026. The test used commit df522c1, built from GitHub in eu-west-lim-a, with port 8000 and a Uvicorn start command in the Procfile. It used Python 3.13 with FastAPI 0.141.1 and Uvicorn 0.52.4. No manual build or start override was set.

The published check record reports six passing checks through the public HTTPS URL:

Open the live health endpoint, try the API interface, or follow the FastAPI deployment guide.

These results cover deployment and HTTP behaviour for a small app without a database. They do not measure uptime, load capacity or end-to-end deployment time. The same record gives a CLI reading at 11:48 UTC of about 0.034 GB of memory and about $0.00051/hour in resource cost. That is a reading at one moment, not a monthly invoice; the quoted reading used the rates in effect at the time. Current Lizard hosting uses pay as you go with no monthly subscription; storage, traffic and payment fees can add to the total. The Dockerfile above is a separate example and does not reproduce that deployment's exact configuration.

Django, Postgres and Celery need separate checks

Connect Managed Postgres through the variable your Django settings read. Run migrations as a controlled release step, not independently in every web worker. Configure static-file handling and give uploaded files durable storage.

Run Celery as a separate service with the same relevant application code and its own start command. Configure the broker explicitly, for example with Managed Redis if your application uses Redis. Check retries, duplicate-task handling and shutdown before accepting production work.

For a server you operate yourself, use the Django VPS walkthrough. For a managed worker, see the worker deployment reference.

Estimate the whole Python application

Include web processes, workers, database, stored files, backups, transfer and the plan your team needs. Railway meters consumption and applies its paid plan toward usage. Render publishes instance plans. PythonAnywhere currently lists Developer at $10/month; check its included features against your app. Sources: Railway, Render, PythonAnywhere.

Lizard has no monthly subscription or per-service plan fee. For a small app averaging 0.01 vCPU and 0.1 GB of memory over 720 hours, with 10 GB of egress, resource charges total about $1.53 before payment fees and tax. Add the database, worker and storage your Python app needs. See the worked example and current rates. Purchased credits do not expire, so a quiet month does not require buying another plan.

FAQ

Can I host FastAPI on the same services as Django? Often, but FastAPI needs an ASGI server. Confirm the host supports your start command and any long-lived connections or workers the app uses.

Should I use runserver in production? No. Use a production WSGI or ASGI server and check the framework's deployment guidance.

Why does the host say my app is unhealthy? Check the build logs, process exit status, import path, bound interface and expected port. Then check missing variables and dependency connections.

Do I need a Dockerfile? Not on every host. A source builder can create the image, but you still need correct dependencies and a production start command.

What is the best host for a Python worker? One that supports the worker's lifecycle and dependencies. Test queue consumption, retries and restart behaviour; an HTTP-only deployment is not enough.

Originally published at Lizard (lizard.build).

You need a VPS with SSH and sudo access, a domain pointed at it, a working Django repository and a dependency lock or pinned requirements.txt. The example uses example.com, /srv/myapp and myproject.wsgi:application as placeholders. It covers a WSGI application; use an ASGI setup if your app requires it. References checked on 9 September 2026.

1. Prepare the server and application user

Install the base packages on the new Ubuntu server:

sudo apt update
sudo apt install -y python3-venv python3-dev build-essential libpq-dev postgresql nginx git
sudo adduser --system --group --home /srv/myapp django
sudo install -d -o django -g django /srv/myapp

The django user runs the application without root privileges. Keep administrative SSH access with your normal account. Allow your SSH connection in the firewall before enabling firewall rules, and permit inbound HTTP and HTTPS. Keep PostgreSQL reachable only where the app needs it.

2. Create PostgreSQL credentials

Create a database role with a password you choose at the prompt, then create its database:

sudo -u postgres createuser --pwprompt myapp
sudo -u postgres createdb --owner=myapp myapp

The application will connect to 127.0.0.1, which uses password authentication under the usual Ubuntu PostgreSQL setup. Confirm your pg_hba.conf if the connection fails. Do not expose the database port publicly to solve a local authentication problem.

3. Install the application and dependencies

Replace the example repository URL. For a private repository, arrange read access without putting a token into the URL or committed files.

sudo -u django git clone https://github.com/your-org/your-app.git /srv/myapp/app
sudo -u django python3 -m venv /srv/myapp/venv
sudo -u django /srv/myapp/venv/bin/pip install -r /srv/myapp/app/requirements.txt

Your requirements must include the Django version, Gunicorn and the PostgreSQL driver your project uses. Use the project's existing package manager if it has a different lockfile. Confirm that the settings module and WSGI import path match your repository.

4. Load production settings explicitly

Create /etc/myapp.env using your editor. Store real values there, not in Git. This example assumes your settings read these names:

DJANGO_SECRET_KEY='replace-with-a-long-random-secret'
DJANGO_ALLOWED_HOSTS='example.com'
DJANGO_CSRF_TRUSTED_ORIGINS='https://example.com'
DB_NAME='myapp'
DB_USER='myapp'
DB_PASSWORD='replace-with-the-password-you-set'
DB_HOST='127.0.0.1'
DB_PORT='5432'

Use simple quoted values compatible with both a shell and systemd's environment-file syntax. Protect the file:

sudo chown root:django /etc/myapp.env
sudo chmod 640 /etc/myapp.env

In the production settings, configure the matching reads. This fragment assumes BASE_DIR already exists:

import os

DEBUG = False
SECRET_KEY = os.environ['DJANGO_SECRET_KEY']
ALLOWED_HOSTS = os.environ['DJANGO_ALLOWED_HOSTS'].split(',')
CSRF_TRUSTED_ORIGINS = os.environ['DJANGO_CSRF_TRUSTED_ORIGINS'].split(',')
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ['DB_NAME'],
        'USER': os.environ['DB_USER'],
        'PASSWORD': os.environ['DB_PASSWORD'],
        'HOST': os.environ['DB_HOST'],
        'PORT': os.environ['DB_PORT'],
    }
}
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'

Keep uploaded media separate from collected static assets. Choose durable storage, a backup policy and access controls appropriate for the uploaded content. See Django's deployment checklist.

5. Check settings and prepare the database

Run management commands as the app user with the same environment as the service:

sudo -u django bash -c 'set -a; . /etc/myapp.env; set +a; cd /srv/myapp/app; /srv/myapp/venv/bin/python manage.py check --deploy'
sudo -u django bash -c 'set -a; . /etc/myapp.env; set +a; cd /srv/myapp/app; /srv/myapp/venv/bin/python manage.py migrate --noinput'
sudo -u django bash -c 'set -a; . /etc/myapp.env; set +a; cd /srv/myapp/app; /srv/myapp/venv/bin/python manage.py collectstatic --noinput'

Review the deployment warnings. HTTPS-related settings come after the proxy has a working certificate. For an existing production database, take and test a backup before applying schema changes. Run migrations once as part of the release, rather than in each Gunicorn worker.

6. Run Gunicorn under systemd

Create /etc/systemd/system/myapp.service:

[Unit]
Description=Django application
After=network.target postgresql.service

[Service]
User=django
Group=django
WorkingDirectory=/srv/myapp/app
EnvironmentFile=/etc/myapp.env
ExecStart=/srv/myapp/venv/bin/gunicorn myproject.wsgi:application --bind 127.0.0.1:8001 --workers 2 --access-logfile - --error-logfile -
Restart=on-failure
RestartSec=5
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

The two-worker value is an initial example, not a sizing formula. Measure memory, database connections and response time before increasing it. Gunicorn binds to loopback so visitors reach the app through nginx.

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp --no-pager
curl -I -H 'Host: example.com' http://127.0.0.1:8001/

Use journalctl -u myapp for process errors. An import failure usually points to the module path, working directory or dependency installation. See Django's WSGI guidance and Gunicorn.

7. Put nginx in front

Create /etc/nginx/sites-available/myapp:

server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /srv/myapp/app/staticfiles/;
    }

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the new site once, test the configuration and reload:

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
sudo nginx -t
sudo systemctl reload nginx

Confirm nginx can read the collected static files and traverse their parent directories. Keep any default site configuration consistent with your other hosted domains; do not remove unrelated sites. The nginx guide explains reverse-proxy and static-file configuration.

8. Add HTTPS and recheck Django

Install a certificate using your chosen ACME client and its current instructions. With Certbot installed for nginx, the certificate request for this example is:

sudo certbot --nginx -d example.com
sudo certbot renew --dry-run

Use the Certbot instructions for installation on your OS. Verify domain DNS, HTTP reachability and renewal before considering TLS complete.

Once HTTPS works, set these Django options:

SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

Trust the forwarded-protocol header only because nginx controls it and Gunicorn is not directly exposed. Restart the service, rerun check --deploy, and test login and a form submission over HTTPS. Review HSTS separately after verifying HTTPS on every affected host.

9. Make future releases repeatable

For each release, choose a reviewed revision, install its locked dependencies, apply any compatible migration, collect static files and restart the service. Test the live application and watch errors after the change.

Keep the previous revision available, but remember that reverting code may not undo a database migration. Document the recovery path for schema changes and test restoring data into a separate database.

If the app uses Celery, give it a separate service definition, command and broker configuration. Do not run the worker as a background shell command inside the Gunicorn service.

When to choose managed hosting instead

A VPS is reasonable when you want server control and can maintain it. If you want to hand off more host operations, compare Python app hosting options. On Lizard, the application can use Managed Postgres and a separate worker, while you keep control of its code and configuration.

The deployment documentation covers that route. You still need correct Django settings, a release process and a verified data-recovery plan.

FAQ

Why do I get a 502 error? Check whether Gunicorn is running and listening on 127.0.0.1:8001, then inspect its logs and nginx's error log. A reverse proxy cannot fix a process that fails to start.

Why are static files missing? Check STATIC_ROOT, the output of collectstatic, nginx's alias path and file permissions. Uploaded media requires a separate setup.

Can I use SQLite instead of PostgreSQL? Some applications can, but assess concurrency, persistence and backup requirements. Do not change the database engine without testing your application's workload.

Is a successful deployment check enough? No. Test a real user flow, database writes, file access and recovery. Configuration checks catch only part of production behaviour.

Originally published at Lizard (lizard.build).

This guide comes from Lizard. We checked the linked product documentation on 9 September 2026. The options below solve different problems; they are not interchangeable implementations of Kubernetes.

Identify the work you want to remove

Write down the tasks your team handles today: cluster upgrades, ingress, certificates, storage, networking, permissions, deployment policies and monitoring. Then identify which tasks exist because your application needs them and which exist because you chose a cluster.

That distinction prevents an expensive migration to another system with the same operating burden. A managed control plane can help with cluster administration while leaving workload and networking decisions to you. A managed app platform can take over more of those decisions while offering fewer low-level controls.

Seven approaches to compare

Managed application platforms

This is the first model to test if your requirements are a public API, a few workers and a database. Lizard exposes that workflow through the Lizard CLI, with Managed Postgres and Managed Redis available as data services.

The trade-off is deliberate: you use the platform's supported controls. If you depend on a particular operator, admission policy or custom network setup, verify that requirement before moving. See the PaaS comparison for other providers and billing models.

ECS and Cloud Run

Fargate can run supported ECS and EKS workloads without making you operate the worker hosts. In ECS, you still define tasks and services and account for the AWS resources around them. Include networking, load balancing and logs in the budget.

Cloud Run provides distinct resource types for services, jobs and worker pools. Match each process to the right type. Do not assume that an HTTP service's scaling and billing settings also describe a continuous queue consumer.

These options can fit a team already comfortable with the relevant cloud's identity and networking model. They are less attractive if avoiding that model is the reason for leaving Kubernetes.

Nomad and Docker Swarm

Nomad is another workload scheduler. Evaluate its job model, supported drivers and operational requirements against your workloads. Choosing a different scheduler does not remove the need for service discovery, persistent data and recovery planning.

Docker Swarm is built into Docker Engine and manages services across a swarm of hosts. It may feel familiar to a team already using Docker, but you still need to maintain the hosts and protect manager availability. Test how persistent data and placement behave when a host fails.

Neither should be selected merely because a demonstration needs fewer configuration lines. A useful evaluation includes upgrades, failed hosts and a real deployment rollback.

Kamal, Coolify and Dokploy

Kamal deploys containerized web applications to servers you provide. It can suit a team that wants a repeatable deploy process without adopting a general cluster scheduler.

Coolify and Dokploy provide deployment workflows on infrastructure you control. Compare their current support for your app, database, domains and deployment source.

With these tools, someone still owns the machine. Plan OS updates, access control, monitoring, disk space and tested backups. The Django VPS guide gives a concrete example of those tasks.

When keeping Kubernetes is reasonable

Keep it on the shortlist when your applications need controls your team already uses well: custom resources, sophisticated workload policy, a shared internal deployment platform or infrastructure features with no simple replacement.

Also consider how much working automation and knowledge you would discard. A migration is useful when it reduces a real cost or limitation. Reducing the number of YAML files is not enough if the replacement adds manual work elsewhere.

Test a move without copying every abstraction

Start from the application contract: image, start command, configuration, port, health check, data and shutdown behaviour. Map those needs to the new host. You do not need an equivalent object for every Kubernetes object if the provider handles the same responsibility for you.

Move one stateless service first. Verify the user flow, error behaviour and resource consumption. Move workers and data only after testing their lifecycle. Preserve the old route until you have a rollback plan that includes new database writes.

Compare operating time as well as invoices. A provider can reduce cluster work while charging more for compute; a VPS can reduce the invoice while leaving more work with your team.

FAQ

Do small applications need Kubernetes? Not by default. Choose it when its controls solve your requirements and your team can operate it. A standard API and worker can often use a simpler deployment model.

Is managed Kubernetes the same as a PaaS? No. A managed cluster usually still leaves workload configuration with you. A PaaS provides a more application-focused contract, though the exact responsibility split varies.

Can I move without changing application code? Sometimes. Configuration, storage and cloud-specific dependencies still need review. Test the app contract rather than assuming image portability means operational equivalence.

Which alternative costs least? Compare your workload and the work required to operate it. Include databases, network, storage, monitoring and recovery; do not rank products by the control-plane price alone.

Originally published at Lizard (lizard.build).

This guide comes from Lizard. We checked the linked pricing and SDK documentation on 9 September 2026. It compares documented behaviour and an illustrative calculation, not measured provider performance.

What a sandbox adds to an agent

An agent can generate a program without having anywhere appropriate to run it. A sandbox supplies an execution environment separate from the application that coordinates the agent.

The coordinator sends code or commands, collects output and files, and decides what to do next. It must also handle a failed command, a timed-out session and cleanup. Isolation is useful, but access to credentials, external systems and private data still requires a deliberate policy.

E2B's quickstart demonstrates code execution and file access through its SDK. Start with a small task and inspect both output and errors before connecting it to a larger agent loop.

E2B pricing: separate the plan from runtime

E2B lists a free Hobby plan with a one-time $100 credit, sessions up to one hour and 20 concurrent sandboxes. Pro lists a $150 monthly base plus usage, sessions up to 24 hours and a higher concurrency allowance. The plan fee is not the runtime bill. E2B pricing.

For an illustrative workload of 1,000 total running hours at 2 vCPUs and 4 GiB, use the published per-second rates:

CPU:    1,000 × 3,600 × 2 × $0.000014 = $100.80
Memory: 1,000 × 3,600 × 4 × $0.0000045 = $64.80
Runtime subtotal: $165.60
With the $150 Pro base: $315.60 before tax and other charges

This E2B example excludes trial credits, tax, paid concurrency add-ons and other usage. Total runtime spans all sandboxes; check session and concurrency limits separately.

The same compute example on Lizard

Assume 1,000 total running hours with Lizard’s meter reading 2 vCPUs and 4 GB of memory throughout. Lizard’s memory meter uses 1,024 MiB per GB, matching the GiB quantity in the E2B example.

CPU:    1,000 × 3,600 × 2 × $0.000006948 = $50.0256
Memory: 1,000 × 3,600 × 4 × $0.000003474 = $50.0256
Compute subtotal: $100.0512, or about $100.05
Monthly subscription: $0

Lizard has the lower compute cost in this example: $100.05 versus E2B’s $165.60. With E2B Pro’s monthly base, the comparison is $100.05 plus Lizard payment fees versus $315.60, before tax. Neither figure includes extra storage, traffic or other services. E2B Hobby has no base fee; do not add Pro’s fee when Hobby meets the requirements.

This is a rate calculation, not a measured performance result. Check limits and retained state before choosing a provider. Sources checked 15 September 2026: E2B pricing and Lizard pricing.

Compare the operating contract

Daytona lists compute, memory and storage separately. Modal's sandbox documentation describes execution, networking and lifecycle controls. Use those specific docs when comparing behaviour; a common word such as “pause” need not mean the same storage guarantee.

Pause is not a backup

For Lizard Sandboxes, pause freezes vCPUs and retains memory and running processes in the host's RAM. It does not write a durable disk snapshot of the whole machine. A host failure can therefore lose that paused state.

The sandbox lifetime also continues while paused. The Lizard SDK documents a default five-minute timeout; opting out of expiration is a separate setting. Save important outputs outside the sandbox and set a lifetime that fits the task. See the Lizard SDK and Sandboxes documentation.

Do not build recovery around a claim such as “resume instantly with everything saved” unless you have checked the exact failure case. Test process failure, expired sessions and unavailable hosts as separate events.

A small Lizard SDK example

Install @lizard-build/sdk in a Node project and provide LIZARD_API_KEY through the environment. Replace my-project with a project you can use. This example creates a short-lived environment, runs one command and releases it in a finally block:

import { Lizard } from '@lizard-build/sdk';

const client = new Lizard({ project: 'my-project' });
const sandbox = await client.create('base', { timeoutMs: 300000 });
try {
  const result = await sandbox.process.exec('node -e "console.log(6 * 7)"');
  if (result.exitCode !== 0) throw new Error(result.stderr);
  console.log(result.stdout);
} finally {
  await sandbox.kill();
}

The command should print 42. The example illustrates the API and cleanup pattern; it is not a throughput or startup benchmark. Production code should also handle a failed cleanup request and preserve outputs it needs before termination.

Test the workflow, not just the first command

Use the same task and dependency set on each candidate. Record time to a usable environment, command execution time, failures, resource consumption and retained outputs. Separate image preparation from session startup so the comparison measures the same stages.

Then test the cases an agent will encounter: a command that fails, a process that hangs, concurrent sessions, a large output and a session that expires. Confirm the coordinator records enough information to retry safely.

If the output is a production application, deploy it as a service with a normal release process. A sandbox URL and a successful test run are not a substitute for deployment configuration, monitoring and durable data. Our Claude Code deployment guide covers that next step.

FAQ

Is E2B free? Its Hobby plan has no base fee and includes a one-time credit, while runtime has published usage rates. Check the applicable limits and what happens after credit is used.

Is Lizard cheaper for the example above? Yes. Its compute subtotal is $100.05, compared with E2B’s $165.60 in usage or $315.60 with Pro’s base. Add Lizard payment fees and any storage or traffic on either host. Lizard does not require a monthly subscription.

Does E2B Pro include unlimited runtime? No. Its base fee and usage charges are separate.

Does pausing Lizard Sandboxes make their state durable? No. Paused memory stays in host RAM, and the lifetime continues. Export important data and plan for expiration or host failure.

Which provider is fastest? This guide does not establish a speed ranking. Measure the same image, dependencies, region and readiness condition, and report repeated results rather than a single successful start.

Originally published at Lizard (lizard.build).

Heroku remains an option too. Its move to sustaining engineering does not mean existing applications have to leave immediately. This Lizard comparison checks the linked sources as of 9 September 2026.

What changed at Heroku

On 6 February 2026, Heroku announced a focus on stability, security, reliability and support rather than new features. The notice says credit-card customers, including new ones, can keep using the product. It does not announce a general shutdown. Read Heroku's statement.

The decision to move should follow a concrete requirement: cost, a needed feature, deployment constraints, or your view of the product's direction. An unsupported claim that the service is closing creates urgency without helping you plan.

Map your Heroku app before comparing hosts

Do this inventory before choosing by the smallest web-instance price. The worker, database and add-ons often decide which option is practical.

Compare the closest operating models

Lizard: choose it for web services and workers with no monthly subscription or per-service plan fee. Purchased credits do not expire. This suits small apps and workloads that vary through the month. Add Managed Postgres and Managed Redis at resource rates, and operate them through the Lizard CLI. The small-app calculation shows how usage can stay below a paid instance minimum. Configure connection variables explicitly.

Railway: evaluate its project and service workflow if you want to manage several parts of an app together. Railway meters consumption; a paid plan includes credit toward usage. It is not a fixed-price replica of a dyno. Railway billing.

Render: evaluate its web and worker instance plans when selected capacity is easier for your team to budget. Price the database and any workspace requirements as well. Render pricing.

Cloud Run: identify whether each process belongs in a Service, Job or worker pool. A direct copy of a Procfile does not define the Cloud Run architecture. Cloud Run resource types.

A VPS with Coolify or another deployment tool: consider this when you want control of the host and can maintain it. A deployment interface does not take over patching, storage durability or disaster recovery. The Django VPS guide shows the work a server-based setup includes.

For more options, use the PaaS comparison.

Compare the full monthly bill

Heroku's published Cedar prices include Basic at \(7/month and Standard-1X at \)25/month. These are dyno prices, not a quote for a web app, worker and database together. Check the foundation and plan your app uses. Heroku pricing.

On any replacement, include every process, database, retained file, network charge and required plan feature. For a metered plan, measure consumption and account for its credit. For fixed instances, count all billed instances and their operating time.

Keep the same workload in the comparison. Do not assume that a replacement uses a fraction of the CPU or memory without running it. Also include a period when old and new systems operate together during the migration.

Move a copy before changing traffic

1. Export a configuration inventory without placing secret values in a public document. Pin runtime and dependency versions.
2. Deploy the web process and worker as separate test services. Verify their start commands and shutdown behaviour.
3. Restore a database backup into a test database. Check PostgreSQL extensions, row counts and application-level reads and writes.
4. Test login, email, uploads, payments in test mode and background jobs. Check callback domains and webhook URLs.
5. Decide how to handle writes during cutover. A maintenance window is often easier to reason about than two writable copies.
6. Take the final backup or finish replication, switch application connections, then change traffic. Watch errors, jobs and database activity.

Keep a rollback plan that includes data written after the switch. Pointing DNS back does not move those writes into the old database.

On Lizard, start from the GitHub deployment guide and variable references. Read the worker settings separately from the web service settings.

When staying is reasonable

Staying on Heroku can be the lower-risk choice when the app meets its requirements, your team knows the operating model, and moving would consume time better spent elsewhere. A mature app can depend on add-ons, release steps and internal practices that no feature table captures.

Write down the change you want from a new host. If a trial does not demonstrate it, a migration has not yet earned its cost.

FAQ

Is Heroku shutting down? The cited announcement does not say that. It describes sustaining engineering and continued service for credit-card customers. Assess the current statement and your contract rather than treating it as a shutdown deadline.

Can I keep my Procfile? It is a useful inventory of process commands. Check which entries your chosen host detects automatically and configure the others as separate services or jobs.

Can I move Heroku Postgres to another PostgreSQL service? Often, but test the version, extensions, roles and restore process. The application must work against the restored data before you switch production traffic.

Will migration reduce costs? Only a complete estimate and a representative trial can establish that. Include the database, workers, storage, traffic and temporary overlap between hosts.

Originally published at Lizard (lizard.build).

The term covers several operating models. A managed Kubernetes cluster, a serverless HTTP container and an always-running application service can all appear in CaaS comparisons, but they leave very different work to your team.

This guide comes from Lizard. Product references were checked on 9 September 2026.

What happens when you deploy a container

A typical deployment has four parts: build the image, store it in a registry, start an instance, and route traffic to it. The provider then observes the instance and handles restarts or scaling according to its rules.

Your image must start the right process, listen on the expected interface and port, and provide configuration in the form the application understands. The platform cannot infer whether a successful HTTP response means the application can write to its database.

For a worker, routing may not be needed at all. The important checks become queue access, process lifetime, retries and graceful shutdown. Treat web and worker runtimes as separate requirements.

CaaS, PaaS, FaaS and IaaS compared

These labels overlap. A PaaS can build a container for you. A function service can accept a container image. Image support alone does not tell you whether a queue consumer can run continuously. Our PaaS guide compares the complete application workflow.

Three ways providers run your image

An application service

Use this model when you want to run a conventional web process or worker. Lizard is one option; Railway and Render are others. Compare their lifecycle, deployment controls and data services rather than assuming every implementation is identical.

On Lizard, you can deploy from source or supply a Dockerfile. Use the deployment documentation to choose the path. Configure non-HTTP services using the worker guide.

A request-driven container

This model starts or scales instances around incoming work. It can suit APIs with uneven traffic. Check concurrency, request timeouts, idle settings and how the provider bills memory as well as CPU.

Cloud Run separates Services, Jobs and worker pools. Match the resource type to the process. A batch program that exits and a web server that receives requests should not use the same deployment assumptions.

A managed scheduler or cluster

ECS and managed Kubernetes give you more control over how several workloads run. You may still need to design networking, permissions, deployment policies and observability.

For AWS, Fargate removes the need to manage the worker machines for supported ECS or EKS workloads. It does not remove the need to understand the surrounding AWS resources. If cluster operation is the problem you want to avoid, read the Kubernetes alternatives guide.

What container hosting leaves with you

Data: decide which data belongs in a database, object storage or an attached volume. A writable filesystem is not proof that files survive replacement of an instance. Test the exact persistence behaviour you rely on.

Secrets: give each service only the values it needs. Confirm that the application reads those values and fails clearly when one is missing.

Release safety: a new image may require a schema migration. Plan the order and compatibility of application and database changes, including rollback.

Recovery: a restart can recover a process. It cannot reconstruct a lost database or repair a bad migration. Test backups and restoration separately.

Capacity: resource limits prevent one service from consuming everything available to it, but they do not establish throughput. Measure latency, errors and queue depth under representative load.

How to estimate CaaS cost

List every billed component: runtime CPU and memory, image storage, builds, persistent storage, internet transfer, load balancing, logs and databases. Include the plan or control-plane fee where one applies.

Then identify the meter. Some products bill allocated capacity for the time an instance runs. Others measure consumption or active request time. A published hourly CPU rate is not comparable until you know what creates a billable hour.

For example, ten containers running concurrently for one hour produce ten container-hours. Ten one-hour runs executed in sequence produce the same runtime total, but they need different concurrency limits. The application may also experience different queue delays. A cost estimate should state both runtime and peak concurrency.

Use AWS Fargate pricing, Cloud Run pricing, Railway billing and Lizard pricing for the relevant meters. Do not reuse one provider's memory or transfer allowance in another provider's calculation.

A short evaluation plan

Deploy a representative service with its real start command. Check its health endpoint, database connection and one meaningful user flow. Restart it and confirm how temporary and persistent files behave. Run enough traffic to observe resource use and latency.

Repeat those checks for a worker if the app has one. Then calculate the bill from the observed meters and the plan your team can use. Choose the model that satisfies the lifecycle and recovery requirements with an operating process you understand.

FAQ

Does CaaS require Kubernetes? No. Kubernetes is one way to schedule containers. Application platforms and services such as ECS or Cloud Run can run containers through other interfaces.

Is CaaS the same as Docker hosting? The terms often overlap. Read the runtime contract: image support, process lifetime, networking, persistent storage and operational responsibility matter more than the label.

Can a container keep uploaded files? Only if the storage setup provides the durability you need. Use a database, object storage or a suitable attached volume and verify behaviour across redeploys.

Can I deploy without writing a Dockerfile? Some providers build an image from source. Lizard supports that path through lizardpack. Check the supported language and project layout in the current documentation.

Originally published at Lizard (lizard.build).

Looking for a provider’s bill? Jump to Render pricing or Fly.io pricing.

We publish this guide at Lizard and include competing options where they fit. Render and Fly.io pricing below was checked on 14 September 2026. Other provider references were checked on 9 September 2026. This is a comparison of documented capabilities, not a benchmark ranking.

Render pricing: web service, database and workspace

A small paid Render app with Postgres costs $14.50/month in this example: \(7 web service + \)6 database compute + $1.50 for 5 GB of database storage, on a $0 Hobby workspace. Rates checked 14 September 2026; USD, before tax and extra usage.

This assumes one app instance and one database for the full month. A second $7 worker makes it $21.50. Pro adds a $25 workspace fee; storage, bandwidth and builds can add charges. This small database example does not include high availability. Render pricing.

Render renamed compute plans in August 2026: 0.5c-512mb was “Starter.” The rename did not change its price or specs. Use current plan IDs when checking a quote. Compute plans.

Can Render be free? It offers free web services with idle spin-down and usage limits. Free Postgres expires after 30 days. That is useful for a trial; budget a paid database for an app you intend to keep online. Free service limits.

Fly.io pricing: Machines, storage and traffic

A Fly.io app costs more than its Machine alone. For a small SQLite app in Ashburn (iad), a 1 GB shared-cpu-1x Machine running for 30 days is about $5.70. Add a 10 GB volume ($1.50) and 100 GB of public egress from North America ($2): about $9.20, before tax and other services.

Rates checked 14 September 2026. This assumes shared IPv4, no replicas and no separate database service. Compute rates vary by region. Volumes remain billable when Machines stop; stopped Machines also incur root-filesystem storage charges. Dedicated IPv4 costs $2/month. Add snapshot storage and any support or third-party services you use. Fly.io resource pricing.

This SQLite example does not price a managed Postgres app. Fly.io charges separately for its managed database service; select its plan and storage in the Fly.io calculator. Use the same database and availability requirements before comparing it with the Render example.

Does Fly.io have a free tier? New accounts get a trial: two total VM hours or seven days, whichever runs out first. Trial Machines stop automatically after five minutes. Adding a card ends the trial and starts billing. Do not use legacy free allowances to estimate a new account. Fly.io free trial.

For worked budgets and current trial rules, see our Fly.io pricing guide.

What a PaaS should do for your team

A platform as a service builds or accepts your application, runs it, and provides tools for deployment and operation. The useful question is how much of your stack it covers.

A web service is only one part of many applications. You may also need a worker, scheduled jobs, a database, uploaded files, logs and a way to restore data. Compare that whole system. A low entry price for one web process does not price a complete SaaS application.

The line between PaaS and container as a service is not strict. Many products accept both source repositories and container images.

A shortlist by use case

See the providers' own Railway, Render, Fly.io, DigitalOcean, Northflank and Coolify pages for plan details.

Compare billing models before prices

Measured resource use: Lizard uses pay as you go with no monthly subscription. Purchased credits do not expire. Running services can still consume memory while waiting. Railway also meters use, with a monthly minimum on paid plans.

Selected instance size: a fixed instance price makes the compute line easier to forecast. You pay for the chosen capacity during its billed lifetime. Other charges can still change the total.

Request-driven compute: charges depend on the provider's treatment of CPU, memory, requests and idle instances. Autoscaling can reduce idle compute, but a database, minimum instance or retained storage can continue to cost money.

Your own server: the VPS invoice buys capacity. Your time and any services for backup, monitoring or email remain part of the cost of running the application.

Our Vercel alternatives guide compares functions with long-running processes and includes a small-app estimate.

Lizard and Railway: the same service usage

Using the published Railway service rates and Lizard rates, take 10 vCPU-hours, 100 GB-hours of memory, 1 GB of Persistent Volumes for 30 days and 10 GB of service egress. No object storage, agent tokens or paid add-ons are included. Rates checked 15 September 2026.

Lizard has the lower resource subtotal and no monthly minimum. It remains cheaper than Hobby in this example if its payment fees allocated to that usage are below $2.91. Railway’s plan payment already covers usage up to its minimum; do not add it twice. Trial credits and tax are excluded. Railway Free can suit smaller eligible projects. Account limits and features differ. Railway plan terms.

Build a budget for the whole application

Use one billing period and one workload for every candidate. Record these inputs before opening a calculator:

• Web and worker process counts, including replicas and staging services.
• CPU use, memory use or allocated capacity, according to the meter.
• Database size, connections, backups and restore requirements.
• Persistent files and object storage.
• Internet egress and traffic between regions or providers.
• Build duration, deploying seats, support and required add-ons.

For a plan whose fee becomes usage credit, the basic formula is plan fee + max(0, eligible usage − available credit) + charges outside that credit. Check eligibility in that provider's terms. Do not subtract an allowance from every service when the provider shares it across the account.

Run the same app on your shortlist and measure it. A hypothetical assumption such as “quarter of a CPU” is useful for a sensitivity check, but it does not prove that a provider will be cheaper for your app.

Where Lizard belongs on the shortlist

Choose Lizard when you want a low resource bill without a recurring plan commitment, along with web services, workers, Managed Postgres and Managed Redis. The Railway example above shows the price advantage for a small paid-plan workload. Unused purchased credits stay available for the next project.

The Lizard CLI supports structured output and ships with a version-matched guide. This helps an agent use the installed commands correctly. It does not remove the need to verify configuration, database access and the live application.

Choose another option when a specific region, contract, compliance requirement or feature is essential and you have not confirmed Lizard supports it. A platform comparison should make those gaps visible before you migrate.

Heroku and App Runner have different status changes

Heroku's February 2026 announcement describes a shift to sustaining engineering. It also says new and existing customers paying by credit card can continue using the service. Calling Heroku closed to all new customers is wrong. Heroku's announcement.

AWS App Runner stopped accepting new customers on 30 April 2026, while existing services remain operational. AWS points users toward ECS Express Mode. That is a different policy. AWS App Runner notice.

If either affects your plans, use the Heroku migration comparison or App Runner guide to assess the work involved.

A useful trial ends with a restore test

Deploy one representative service, connect its dependencies and run a real user flow. Check a failing build, a process restart and a database connection failure. Confirm where logs appear and how you would restore a backup.

Then compare the bill and the time spent operating the app. Choose the provider that meets those requirements with a process your team can repeat. Start with the deployment documentation if you want to include Lizard in that trial.

FAQ

Is a PaaS cheaper than a VPS? Not in every case. A VPS can have a lower infrastructure bill, while a PaaS can reduce server administration. Compare both the cash cost and the work your team must perform.

Does a PaaS include a database? Some providers offer databases in the same product, some integrate another vendor, and some require a separate cloud service. Check the database bill, backup policy and network path.

Can I run Celery or another queue worker? Check worker support explicitly. An HTTP function is not the same lifecycle as a process that polls a queue. Our Python hosting guide covers this distinction.

Should I choose by the lowest CPU rate? No. Compare the billing unit, measured or allocated capacity, plan terms and the whole application. Different meters can make similar rates produce different bills.

Originally published at Lizard (lizard.build).

Lizard belongs in the hosting part of that decision. This guide comes from Lizard and checks the linked documentation as of 9 September 2026.

Separate development from production

The workspace where you edit code and the deployment serving users have different jobs. A development workspace favours quick iteration and inspection. Production needs a repeatable build, stable configuration, data durability and a recovery plan.

Replit documents its publishing workflow and deployment options separately from development. Read the current option your application uses before assuming that leaving the editor requires moving its deployment, or vice versa.

Do not compare a development subscription with a hosting-only price as if they buy the same thing.

If you want a different coding workflow

A local editor or terminal agent lets you work in a normal repository and choose where the app runs. The useful comparison is how well the tool handles your language, tests and project size, and what control you have over its edits and actions.

For example, Claude Code works with a codebase and tools in its environment. Deployment still needs a host and credentials for the chosen workflow. Our Claude Code deployment guide explains how to connect those parts.

Try the same bounded coding task in each candidate: fix a bug with a failing test, add a small feature, then inspect the diff. That is more useful than comparing how polished the first generated screen looks.

If you want a browser development environment

GitHub Codespaces provides a development environment tied to a repository. It can help a team share configuration and work from a browser or supported editor.

Treat it as a development choice. Decide separately where the public app runs, how deployments start and where production data lives. A forwarded development port is useful for testing, but it is not a complete production operating plan.

If you want another production host

Choose by the process your application starts and the services it needs. A static frontend, an HTTP API, a continuous worker and a stateful backend have different requirements.

Lizard is an option for an application with web services, workers and managed data services. Railway and Render are other candidates for a multi-service app. Cloud Run is worth evaluating for supported service, job and worker models. Use the PaaS comparison to narrow the choice.

A host will not repair assumptions hidden in generated code. Before moving, look for development-only start commands, local file paths, hardcoded domains and credentials. Verify that the app reads production configuration from the expected variables.

What to export before moving

Source and dependencies: keep the application code, lockfile, runtime version and build instructions in a repository you control.

Configuration: list variable names and which process uses each one. Transfer secret values through the target's secret settings, not a public export or a committed file.

Data: identify the actual database and file stores. Downloading source code does not export database records or uploaded files.

Integrations: record OAuth callback URLs, payment webhooks, email settings and any external API restrictions.

Operations: identify scheduled work, queues and the checks that show a successful deployment.

A practical move to Lizard

First, run the exported project locally using its documented production command. Resolve missing dependencies and environment variables before changing hosts.

Deploy a test copy using the GitHub integration or source upload. Add Managed Postgres if your application uses PostgreSQL, then configure its connection variable explicitly. If it uses a different database, assess compatibility rather than replacing the engine blindly.

Test login, one database write, a file upload, a background task and any external callback. Restart the test service and confirm which data survives. Then plan the final data transfer and domain switch.

Keep a record of the old deployment and how to return traffic if the new one fails. If users can write data during the transition, the rollback plan must account for those new writes.

Compare cost without losing part of the bill

Replit's pricing page distinguishes plans and included usage. A replacement may split coding, development compute and hosting across several invoices.

Add those parts together: the coding tool, development environment, app services, database, storage and network. Apply credits under each product's rules. Include the time spent connecting and maintaining the separate tools.

With Lizard, the hosting part has no monthly subscription: you pay for resource use and keep unused purchased credits. This avoids a recurring hosting plan commitment while you use your own coding tool. Compare that combined cost with the Replit plan you would otherwise need; editor and model access remain separate products.

FAQ

Can I build in Replit and host elsewhere? You can move a portable application to another host while keeping your preferred coding workflow. Check export options, dependencies, data and the production start command.

Is Lizard an AI app builder? This comparison covers Lizard as the place to deploy and operate the application. Your coding tool remains a separate choice.

Does exporting the repository move my database? No. Identify and export the database and file stores separately, then verify the imported data and application behaviour.

What should I test before switching the domain? Authentication, database writes, file access, callbacks and background jobs. Also test a restart and confirm that the rollback process handles new writes.

Originally published at Lizard (lizard.build).

The public repository includes the pinned image, workflow, table definition and check script. This article covers a single n8n instance and JSON requests. For the broader hosting setup, start with n8n hosting on Lizard.

What the example runs

The n8n service and its dedicated Managed Postgres run in the same region. Postgres holds both n8n's own workflow and credential records and the example's webhook_events table. The application uses one instance; there is no Redis queue or separate worker in this example.

The repository pins n8n 2.38.5 and the official image's digest. A fixed digest makes the image choice reproducible. Review later n8n releases and test upgrades before changing the pin.

The workflow has three nodes:

1. Webhook accepts a production POST request with an X-Example-Key header.
2. Store event executes a parameterised Postgres query.
3. Respond returns the stored request ID, JSON body and creation time.

Configure the database, owner and public URL

Create a service from the repository and a separate Managed Postgres in the same Lizard project. The repository instructions list the commands and environment variables.

Set DB_TYPE=postgresdb and bind the database host, port, name, user and password to the addon's variables. A database running beside n8n is not enough: n8n must receive those values and connect successfully. See n8n's Postgres configuration.

Generate and retain a separate N8N_ENCRYPTION_KEY before the first start. n8n uses it to protect credentials stored in its database. A new random key on each deployment would prevent n8n from reading the old credentials. Keep the key with your recovery records, outside the repository.

The example also configures the owner before n8n becomes reachable. It uses N8N_INSTANCE_OWNER_MANAGED_BY_ENV and a bcrypt password hash, following n8n's owner configuration. The login password and the webhook key are separate secrets.

Set N8N_HOST to the service's public hostname, without a scheme or path. The start script builds the HTTPS WEBHOOK_URL and editor URL from that hostname. Use port 5678. Check the proxy-hop setting if you add another proxy in front of Lizard.

Import and publish the workflow

Create webhook_events with the SQL file in the repository. Import the Postgres and header credentials into n8n, then import the workflow. The credential preparation script reads secret values from the service environment and writes a private temporary import file; the public workflow contains only credential IDs and names.

Use the n8n editor to publish the workflow, or use n8n publish:workflow --id=lizardPostgresExample. CLI publication changes the database; the running n8n process needs a restart to register that change. This behaviour is documented in the n8n CLI guide.

Check /healthz/readiness before sending requests. The production URL uses /webhook/lizard-postgres-example. The /webhook-test/ URL belongs to an editor test session and is not a substitute for a published workflow.

Send a request and test a retry

With the public URL and webhook key in environment variables:

curl --fail-with-body "$N8N_URL/webhook/lizard-postgres-example" \
  -H 'Content-Type: application/json' \
  -H "X-Example-Key: $EXAMPLE_WEBHOOK_TOKEN" \
  --data '{"requestId":"example-001","message":"hello"}'

The SQL query binds the request ID and JSON body as values. It does not build SQL by joining user input into the query text. Quotes and nested JSON remain data.

The table's primary key is request_id. On a conflict, the query returns the first saved row. Sending the same ID with a different message does not change the original payload. That is this example's retry policy; choose a different policy if your application needs updates or conflict errors.

Use a new request ID for each distinct event. Do not reuse a test ID to represent a new event and expect a second row.

Deployment checks

On 9 September 2026, we ran n8n 2.38.5 with Postgres 18.6 in eu-west-lim-a. The same seven checks passed before and after restarting the n8n service.

The database held one event after both runs. The JSON body and creation time matched across the restart. The test body included quotes and nested JSON. The owner also signed in and found the imported workflow in the editor.

Read the deployment record and raw results. The record names the tested code commit. Run the repository's check script against your own deployment before using it for your workflows.

What these checks do not cover

The example does not test load, uptime, cold-start latency or a full monthly bill. It does not set up queue mode, database backups, file uploads or recovery from database loss.

A service restart check establishes that this deployment can read its saved workflows and credentials after restarting. It does not establish disaster recovery. For that, take a database backup, retain the encryption key, restore into a separate environment and run the workflow again.

This JSON workflow does not require a persistent local filesystem. Workflows that read or write local files need suitable storage and their own persistence tests. Review Persistent Volumes and n8n's storage requirements before adding that workload.

FAQ

Does n8n need Postgres? No. Self-hosted n8n can use SQLite. This example uses Postgres to keep workflow, credential and execution records outside the application container and to demonstrate a database-writing workflow.

Why does a webhook work in the editor but return 404 elsewhere? Check that the workflow is published and that the sender uses the production /webhook/ path. A CLI publication also requires the running n8n process to restart.

What must stay the same after a redeploy? The database connection must point to the intended database, and the encryption key must still decrypt its credentials. Keep the public webhook URL and authentication contract stable for callers.

Is this a complete production n8n setup? It is a checked single-instance example. Add backups, monitoring, storage and a capacity plan for your workload before depending on it for production automation.

Originally published at Lizard (lizard.build).

This guide is for a Next.js application you already run locally. It uses Lizard for the app and Managed Postgres for the database. You can use the prompts in Cursor's desktop agent, inspect its plan, and let it run the steps you approve.

What needs to move off your laptop?

Consider a task app: you add a task, mark it done, and come back later. Publishing the page is only part of deploying it. The server must reach the database, the tables must exist, and new requests must read the saved data.

Your local database and .env.local file do not move with a GitHub push. Decide which data you need to keep. A fresh database is suitable for a new app; moving an existing database needs a separate export and import plan.

1. Check the production build in Cursor

Open the application folder in Cursor. Ask the agent to inspect the project before changing its deployment settings:

Prepare this Next.js app for deployment with PostgreSQL. Read its package.json,
lockfile, Next.js configuration, database client, and migration files.

Run the existing checks and production build using this project's package
manager. Identify the start command, port, required environment-variable
names, and production migration command. Do not print secret values.

Check whether any page queries the database during the build. Explain what
must be available at build time and what the app can read at request time.
Show any fixes needed before deploying.

A development server can work while the production build fails. For a standard Next.js Node.js deployment, the build uses next build and the server uses next start. Static export and standalone output need different launch settings. Follow the Next.js deployment guide for the configuration your app uses.

Keep the lockfile in source control. Keep database credentials out of it. A variable such as NEXT_PUBLIC_DATABASE_URL would expose a secret to the browser: Next.js includes NEXT_PUBLIC_* values in client JavaScript at build time. Use a server-only DATABASE_URL. Next.js environment-variable docs explain the distinction.

2. Give Cursor the current deployment instructions

Cursor's agent can run terminal commands. Install Lizard CLI in Cursor's terminal if it is not already available:

npm install -g @lizard-build/cli

Then ask the agent to run and read:

lizard skills get core --json

The command returns the guide that matches the installed CLI. This workflow uses the CLI directly; you do not need to configure an MCP server. If Lizard requests authentication, complete the sign-in link before continuing.

Paste this deployment prompt into Cursor:

Deploy this app with Lizard and Managed Postgres. First read the full output
of `lizard skills get core --json`. Check the current project link and git
remote, then show me the target project, service, region, and resources.
Wait for approval before creating resources or changing a live service.

If this app has a GitHub remote, connect that repository without starting
the first build. If it has no GitHub remote, use local source upload.

Create or select the intended database. Set DATABASE_URL on the app service
using a reference to that database's actual name. Configure the app's other
required variables and its reviewed production migration command before
deploying. Keep secret values out of the chat and repository.

Use the build settings this project needs. Read build and runtime logs,
check the final deployment status, and return the public URL. Test the
app's database-backed action and report what passed or failed.

The coding agent guide contains the full commands for both source paths. Keep that guide available while reviewing the agent's work.

3. Connect Postgres before the first deploy

A service can build successfully and then fail on its first database request. Configure the connection before starting that first build or release.

For a new service named web in the intended linked project, with the app at the GitHub repository root, the connection step looks like this. Replace YOUR_ORG/YOUR_REPO with your repository:

lizard add --repo YOUR_ORG/YOUR_REPO --name web --no-deploy --json
lizard add postgres --json
lizard secrets set DATABASE_URL='${{postgres.DATABASE_URL}}' --service web --json

Reuse an existing service or database when that is the intended target. The example assumes the new database is named postgres. If Lizard returns another name, use it in the reference. The single quotes keep your shell from interpreting ${{...}}.

--no-deploy leaves time to configure the database, migration command, and other required settings. For a monorepo or another branch, also set the app directory and branch before deploying. See Managed Postgres for connection details.

If you have no GitHub remote, the agent can create an empty service and upload the local source with lizard up. For a GitHub service, use its GitHub deployment flow for later updates: lizard up changes the service to uploaded source. The two paths are separate choices.

4. Apply the schema your app expects

Creating PostgreSQL does not create your app's tables. A connection error and a missing-table error need different fixes.

Use the migration tool already in the project. For Prisma projects with committed migration files, prisma migrate deploy applies pending migrations in production. Prisma recommends running it through the deployment process. It does not generate Prisma Client, so the build still needs any generation step your project requires. Prisma's deployment docs cover that setup.

Have Cursor configure the service's preDeployCommand with the reviewed migration command. Ensure the built image contains the migration files, the required CLI package, and its configuration. If the migration needs a database connection, that connection must be available when the command runs. Avoid a development reset command against data you need to keep.

Next.js can also read data while building a page. A database connection configured for the running server does not prove that a build-time query will succeed. Ask Cursor to check when each query runs and use the rendering behavior the page needs. The Next.js self-hosting guide covers runtime and build-time behavior.

5. Verify saved data at the public URL

Read the deployment result and open its HTTPS URL. Test the feature that needs Postgres, rather than stopping after the home page loads.

For a task app, use this sequence:

1. Create a task with a name you can recognize, such as deployment-check-0909.
2. Reload the page and confirm the task appears.
3. Open a private browser window, sign in to the same account if needed, and check the task again. This helps catch apps that only save to browser storage.
4. Deploy a small code change through the same source path. Confirm the task still exists and that you can update it.

Adapt the check to your app: a booking, note, or form submission can serve the same purpose. Use test data and check that each account can access only its own records before inviting users.

If a check fails, give Cursor the failed action and ask it to inspect the service logs:

lizard logs --build --service web --json
lizard logs --service web --json
lizard ps --json

The first command reads build logs; the second reads application logs. Keep the logs reference open for filters and troubleshooting.

Why does a Cursor app work locally but fail after deployment?

The deployed app may have different variables, a new database, or a different start command. Match the symptom to the relevant check:

Ask the agent to fix the cause shown in the logs. Repeated deployments with the same configuration will not fix a missing variable or table.

How much does it cost to host the app and Postgres?

Lizard uses pay as you go with no monthly subscription. New accounts receive $10 in free credits, valid for 31 days. Purchased credits do not expire. Resource usage draws from your account balance; the top-up screen shows any payment fee before you confirm. See current rates and payment terms.

The application and Managed Postgres both consume resources. Lizard uses billing only for active resources, with charges for CPU, memory, storage, and outbound traffic under the plan's terms. Stopping an app does not stop a separate database, and retained volume storage can still incur charges.

Measure the app and database together under the load you expect. A trial credit is a way to test the deployment; it is not a promise of permanent free hosting or a fixed monthly cost for every app.

Questions before you deploy

Do I need to export my app from Cursor?

For a local project, your source files are already in the project folder. Deploy that code through a connected GitHub repository or local upload. Check that the source includes the files needed to build and run it.

Does a Cursor subscription pay for Lizard hosting?

No. Cursor and Lizard are separate services. This workflow uses Cursor to operate Lizard CLI; the Lizard account pays for the deployed app and database under its own plan.

Can I keep my existing PostgreSQL database?

Yes, if the deployed server can reach it and its connection settings meet the database provider's requirements. Configure the server-side connection string, check network access, and run the same application tests. You do not need to create another database just to use this workflow.

Do I need a custom domain before deploying?

Start by checking the public address Lizard returns for your web service. Once it works, follow the custom domain instructions to connect your hostname and verify the DNS records. If your app uses login callbacks, update those URLs too.

Open your project in Cursor and start with the preparation prompt above. For the exact deployment sequence, use the coding agent guide.

Originally published at Lizard (lizard.build).

Chrome with Lizard Studio: the page, inspector and chat stay in one window. This screenshot shows the ChatGPT connection.

A visual editor for Claude Code should help you identify the part of a page you want to change and check the result in the source. In Lizard Studio, you select an element in Chrome, attach it to a chat and ask Claude Code to edit your local project. The browser stays beside the conversation so you can inspect the outcome.

This guide uses a small spacing exercise with a result you can measure: change the gap between two buttons from 4px to 24px. You will check the source diff, refresh the page and inspect the gap again. It is a reproducible exercise, not a performance benchmark or a claim about how quickly an agent will finish your project.

We build Lizard Studio. Its extension and host are free and MIT licensed; your AI provider's account requirements and usage charges still apply. Complete the setup guide before trying the agent steps below.

What visual editing means here

Lizard Studio uses an element selector and design tools to give the agent context. You describe a source change; Claude Code makes the file edit. This workflow differs from manually dragging an element and expecting the editor to write the corresponding CSS immediately.

The selector can identify the target on the page. An annotation can show an issue that covers a larger area. Rulers, distance measurements and responsive preview help you check a layout. The local agent connects that page context to your project files. The README lists the tools and connection requirements.

If direct drag-and-drop editing is your main requirement, compare the controls before choosing a tool. This exercise tests selecting an element, requesting a change and reviewing source code.

Download the example

You need Python 3 for the small static server used here, Chrome, Lizard Studio and a signed-in Claude Code installation. For an existing app, use its normal development server instead.

Create an empty folder for the exercise. Download spacing.html into it using your browser's Save page as command, or run this from the folder:

curl -fsS https://lizard.build/studio-examples/spacing.html -o spacing.html
python3 -m http.server 4175 --bind 127.0.0.1

Open http://127.0.0.1:4175/spacing.html in Chrome. Leave the server running while you work. If port 4175 is in use, choose another port and use that number in the URL.

The page has two sample buttons with no actions. Their row intentionally uses this CSS:

.actions {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
  margin-top: 24px;
}

Choose this folder in Lizard Studio so the agent can edit spacing.html. Opening the example on lizard.build only shows the published exercise; changing your downloaded copy requires the local URL.

Select the row you want to change

Start a Claude Code chat in the side panel. Use Selector and attach the .actions row that contains both buttons. If you select one button by mistake, select its parent row or explain that the row's gap is the target.

You can ask for a read-only check before editing:

Inspect the selected action row. Report its computed gap and the
local file that defines it. Do not change any files yet.

The initial gap should be 4px. The source is the stylesheet inside your downloaded spacing.html. If the agent reports another file or page, correct the project folder or browser tab before requesting an edit.

Crops from the Lizard Studio interface show the style inspector and page toolbar. These values belong to the selected element on the ChatGPT overview page; the spacing exercise uses a separate local file.

Ask for a small source edit

Send the selected row with a request that states the result and the scope:

Set the selected action row's gap to 24px in spacing.html.
Keep the button labels, colors and card margin unchanged.
Show the source diff. Refresh the page and check that the
computed gap is 24px.

Review the agent's proposed edit. The relevant change should be equivalent to:

- .actions { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 24px; }
+ .actions { display: flex; flex-wrap: wrap; gap: 24px; margin-top: 24px; }

The agent may reformat the stylesheet. Check the actual declarations rather than requiring the same line layout as this example. There should be no reason to change either button label or the .card rule for this task.

Use your session's permission controls to approve the intended edit. A narrowly scoped request makes the diff easier to judge, but it does not replace reviewing the result.

The real request field shows an attached element as “1 selection.” This screenshot uses ChatGPT and a brightness request; for this exercise, choose Claude Code and use the spacing request above.

Verify the page after a refresh

The Python server does not provide hot reload. Refresh Chrome after the file changes, then ask the agent to inspect .actions again.

You can also check the computed value in Chrome DevTools:

getComputedStyle(document.querySelector('.actions')).gap
// Expected: "24px"

Check both desktop and a narrow viewport. The sample row uses flex-wrap: wrap, so buttons can move onto another line when space is limited. At each width, confirm that the page has no horizontal overflow and both labels remain visible.

Use this acceptance checklist:

• The local source contains gap: 24px for .actions.
• A page refresh preserves the new gap.
• The button text and colors stay unchanged.
• The .card margin stays 32px.
• The page remains usable at a narrow width.

If the project uses Git, read git diff. For this standalone file, your editor's comparison view can show the same change. The exercise is complete when the file and browser agree.

Why a change can disappear

A browser tool can change the live DOM or add an inline style without changing any project file. That can help preview an idea, but the browser loads the original source again on refresh.

If the result disappears, ask the agent which file it edited. Check that the browser uses the local server and that the selected folder contains the served file. An app can also have a more specific CSS rule or inline style that overrides the edited declaration.

For React or another framework, the source may be a component, CSS module or utility class rather than a standalone stylesheet. Ask the agent to find the rule that owns the spacing. Avoid a global button rule when only one action row needs to change.

Use the same method for a real UI issue

Choose an issue with a result you can describe: a card that overflows at a stated width, a heading that should wrap to fit its container or a button row with the wrong alignment. Attach the relevant element or annotated screenshot, then state what should remain unchanged.

For a behavior bug, ask the agent to reproduce the action and inspect console and network output. A screenshot cannot show whether an event handler ran or a request failed. Lizard Studio includes those browser tools; the comparison with Claude in Chrome explains the different setups.

You can also run the exercise with ChatGPT in the side panel. Keep the same starting file and acceptance criteria if you want to compare the two agents. Record failed attempts and clarifications, and avoid drawing speed claims from a single run.

Common questions

Does Claude Code need a screenshot to edit CSS?

A screenshot can help explain a visual problem. In this workflow, the selected element and live page inspection add DOM and style context, while the local folder supplies the source. Use the inputs that help identify your specific issue.

Can I edit any website permanently?

You need access to the source project to keep a source change, and you need to deploy it to update a live site. Inspecting a third-party page does not grant either permission or repository access.

Is this a replacement for my editor?

You can keep using your editor for code and diffs. Lizard Studio supplies the browser side panel and page tools. Compare the other interface choices in the Claude Code GUI guide.

Where do I start if the panel does not connect?

Follow the installation and troubleshooting guide. Check the local host, your agent login and the chosen project folder before testing a source edit.

Originally published at Lizard (lizard.build).

This guide compares five interfaces by workflow rather than assigning an overall score. We build Lizard Studio. We checked the linked product documentation on September 14, 2026; we did not run a controlled speed or reliability benchmark across all five tools.

Compare the interfaces

“Claude Code UI” is also a name used by specific projects. If you found a particular repository or app under that name, check its publisher and installation instructions rather than assuming that all GUI results describe the same product.

Claude Code Desktop: the official standalone app

Anthropic's Code tab brings sessions, file changes and app previews into its desktop application. Its documentation covers local and remote environments, permissions and reviewing diffs. It is a sensible first option if you want an official GUI without making your code editor the center of the session.

Read the desktop reference for current capabilities and desktop setup for supported systems and accounts. Avoid choosing from an old screenshot: the preview and session controls can change between releases.

For your evaluation, open a small project and ask for one file edit. Check whether the preview reaches the route you need and whether you can trace the resulting change back to the right file. If your app depends on a particular browser login, include that requirement in the test.

Claude Code for VS Code: work beside your files

The official VS Code extension places Claude Code in the editor. Anthropic documents context selection, reviewing changes and connecting browser capabilities. It suits a workflow where you already navigate components and inspect diffs in VS Code.

Use the official extension guide to check installation and current browser support. The extension and the desktop app are different interfaces; compare the version you actually intend to use.

Try a task that crosses a component and its stylesheet. Check how you attach source context, review both changes and verify the rendered page. If you spend most of your time in files, staying in that interface may require fewer steps than moving the chat into Chrome.

Lizard Studio: inspect and edit beside the live page

A real Lizard Studio session: the selected element and inspector sit on the page, while the request stays in Chrome’s side panel. This screenshot shows the ChatGPT connection.

Lizard Studio is a free, MIT-licensed Chrome extension. It runs Claude Code or ChatGPT through a local CLI and connects the session to your browser and project folder. ChatGPT is the panel's name for the Codex CLI connection.

The page toolbar includes Selector, Annotate, rulers, guides, a column grid, a color picker, distance measurements and responsive preview. Browser tools let the agent inspect the DOM, screenshots, console and network, then interact with the page as part of the task. See the source and tool list.

Choose this workflow when the change starts with something you see: a cramped button row, an element at the wrong size or an error that appears after a click. Select the element or mark the area, describe the result and review the source diff.

The setup requires a local host and an installed agent. The free extension does not include model use. Your selected provider sets account eligibility, limits and charges. Read the setup guide and try the spacing exercise before deciding.

The documented design workflow uses selections and prompts to request code edits. If you need to drag a control and have it write CSS directly, check tools built around that operation.

Clodex: direct visual controls for source edits

Clodex describes a desktop workspace that runs Claude Code against a local project and adds visual controls to its preview. Its guide covers changes such as spacing, size, typography and text, with edits written to the source files. That makes it relevant when hands-on visual editing is a central requirement.

Read its visual editor guide for the supported operations and limits. It states that you bring Claude access and that its desktop product has paid plans. Check current terms before installing.

A useful trial is a layout change in your own component structure. Check whether the visual control edits the declaration you expect, and inspect the file after a later agent request. A control that works well on a simple page may need a different workflow for nested layouts or shared design tokens.

Nimbalyst: visual work alongside coding sessions

Nimbalyst presents itself as a visual workspace for Claude Code and Codex, with editors for several kinds of project material. Consider it if the same task involves code, plans or visual documents and you want to work with them in one application. Its current product page lists the available editors and agent connections.

Evaluate the editor you need rather than the number of features on the page. Open a representative file, make a small change and check the saved format. Then ask the agent to work with the result. That shows whether the visual document remains useful in your existing repository and review process.

Choose from the task you repeat

For code-heavy work, begin with the desktop or VS Code interface you already understand. For page-led work, test how quickly you can identify the element and supply the intended change. For manual visual design, check whether the controls write ordinary source changes that your team can review.

Use the same acceptance criteria for each tool:

1. The session opens the intended repository and page.
2. The agent or editor changes the expected source file.
3. You can read and approve the diff.
4. The result persists after refresh.
5. A second viewport or related page still works.

Add one requirement specific to your project, such as a CSS module, a shared component or a page that requires a test login. Do not use a different model and a different task for each interface and treat the results as a clean comparison.

GUI, visual editor and browser automation

These terms describe different parts of the workflow. A GUI is an interface for using the agent. A visual editor offers controls for changing a design. Browser automation lets an agent inspect or operate a page. One product can provide several of these, but the presence of one does not establish the others.

When you read a feature page, look for the exact operation you need. Can you select a rendered element? Does a control edit the source or only the live DOM? Can the agent inspect a failed request? How do you see and approve the file diff?

The Lizard Studio and Claude in Chrome comparison covers the two browser setups in more detail. Both can support debugging; design controls, agent choices and session setup are more useful criteria than a broad claim about browser access.

Common questions

Is a GUI required to use Claude Code?

No. You can use its terminal interface. A GUI changes how you give context, inspect sessions and review results; choose it when those controls help your work.

Does a free GUI include free model use?

Not necessarily. Lizard Studio's extension and host are free, while the connected provider supplies agent access. Check software cost and model access separately for every tool.

Which one should I try for CSS fixes?

Try a tool that can identify the rendered element and connect it to a source edit. Use this downloadable spacing exercise to check the file diff and the page after refresh. If you prefer direct visual controls, include that requirement in your trial.

Can I use ChatGPT in Lizard Studio instead?

Yes, through the local Codex CLI connection. The ChatGPT guide explains the naming, setup and a source-editing example.

Originally published at Lizard (lizard.build).