Eden quickstart

An Eden administrator creates your customer account, allocates licenses, and sends your first administrator an invitation. Open that link, sign in through Cloudflare, and accept the terms. Your administrator can then invite the other members of your account at dash.eden.dev.

Use the CLI and image from the same qualified minor release. A platform without a published package or an account without an active license fails explicitly.

The single-container path below needs a Linux amd64 host with Docker Engine, curl, jq, OpenSSL and uuidgen. Kubernetes, PostgreSQL and ClickHouse are not required for this profile. You will install the CLI, approve browser login, download the image, then configure and start that image. The dashboard account and the organization inside your running Service have separate sign-in sessions.

1. Install the CLI

You need curl, tar with gzip support, and sha256sum (or shasum).

curl -fsSL https://eden.dev/eden/install.sh | sh

The published CLI package supports Linux amd64. The installer detects your operating system and architecture, downloads the matching published package, verifies SHA-256 and its version, and installs eden in $HOME/.local/bin. Add that directory to your shell's PATH if prompted. Set EDEN_INSTALL_DIR to an absolute directory to choose another location; installation does not require sudo. A platform without a published package stops before replacing an existing CLI.

eden --version
eden

Running eden with no command shows the quickstart when no prepared local installation or unchanged CLI-downloaded image is available. You can run it again from another directory. Existing prepared local installations keep their normal startup behavior; downloading an image alone does not start it.

2. Sign in through your browser

eden login

Open the displayed link on your laptop or phone and enter the short code. Sign in through Cloudflare, review the terminal request, choose your customer account and an active license, then approve. The terminal waits for that decision. This works on a remote server without a browser or a localhost callback. The code expires after ten minutes.

The CLI saves a private, short-lived download session. Passwords and Cloudflare tokens stay out of the terminal. Choosing an account or license in the browser does not configure a running Eden image. Use eden disconnect to revoke this terminal's download session.

3. Download the latest image

eden image pull --output eden-image.tar.gz

You can pull directly after browser approval. To browse published versions or choose between multiple images, run eden image list. Its product, flavor, edition, architecture and channel fields identify each distinct image. To select the single-container Eden image explicitly, add --product eden --flavor single to the pull command. Use a new output path; existing archives are never overwritten. Images default to linux-amd64. Use --architecture linux-arm64 only when that image is published, and --edition or --channel when needed to select one entry from the catalog. These filters do not change what your license permits. Release channel selection does not change online/offline license validation.

The license server checks current membership, license status, entitlement and the latest release again before delivery. Historical versions are visible; only the latest eligible minor release can be pulled. The CLI verifies the downloaded archive's length and SHA-256, then prints its version, checksum and local path. docker load can read the compressed archive directly.

Load the verified archive into your container engine:

docker load --input eden-image.tar.gz

Retain the image reference printed by docker load. Download history records account authorization for a version; it does not prove that the image is running.

4. Configure the image's license and start it

Open Licenses in your customer account. For an active online license, a customer account owner or billing administrator can select Configure license. Review the replacement notice, acknowledge that the previous credential will stop working, then choose Get license credential and Download license environment file.

This uses the licensing authority's normal authenticated credential operation. It does not allocate another license or extend its term. If a request fails, use Retry request so the original operation is recovered. The credential is kept only in the dialog's private download and is cleared when the dialog closes. Keep the downloaded eden.license.env private and copy it to the host running Eden, for example /secure/eden/eden.license.env.

The file supplies required online enforcement, the authority-issued credential, the licensing URL and validation intervals. The license UUID shown during CLI login is an identifier; a CLI download session cannot replace the runtime credential. Do not paste credentials into command arguments, shell history or support messages.

Keep your deployment's stable EDEN_CLUSTER_UID and its normal authentication, encryption, bootstrap and datastore settings in a separate private runtime environment file. The license download deliberately leaves these values unchanged.

For a new single-container installation, use a private directory and generate the following file once. These commands require OpenSSL and uuidgen; the shell refuses to overwrite an existing runtime file.

mkdir -p "$HOME/.config/eden-runtime"
chmod 700 "$HOME/.config/eden-runtime"
cd "$HOME/.config/eden-runtime"
(
  umask 077
  set -euC
  eden_bootstrap=$(openssl rand -hex 32)
  eden_jwt=$(openssl rand -base64 32)
  eden_encryption=$(openssl rand -hex 32)
  eden_deployment=$(uuidgen | tr '[:upper:]' '[:lower:]')
  eden_instance=$(uuidgen | tr '[:upper:]' '[:lower:]')
  cat > eden.runtime.env <<EOF
EDEN_PORT=8000
EDEN_TURSO_PATH=/var/lib/eden/control.db
EDEN_DUCKDB_PATH=/var/lib/eden/telemetry.duckdb
EDEN_DUCKDB_TEMP_DIRECTORY=/var/lib/eden/duckdb-tmp
EDEN_TELEMETRY_DURABLE_STORE_ENABLED=true
EDEN_ANALYTICS_ENABLED=true
EDEN_LOGS_ENABLED=true
EDEN_EMBEDDED_HTTP_BIND_ALL=true
EDEN_NEW_ORG_TOKEN=$eden_bootstrap
EDEN_JWT_SECRET=$eden_jwt
EDEN_DB_ENCRYPTION_KEY=$eden_encryption
EDEN_CLUSTER_UID=$eden_deployment
EDEN_SERVICE_DEPLOYMENT_UUID=$eden_deployment
EDEN_SERVICE_INSTANCE_UUID=$eden_instance
EOF
)

Copy the downloaded eden.license.env into the same directory. Retain this runtime file and the persistent volume across restarts: replacing an encryption key can make existing data unreadable. Other deployment profiles require their matching container deployment settings.

Set EDEN_IMAGE to the exact reference printed by docker load. Set both files to mode 0600 and pass them when creating the container:

chmod 600 eden.runtime.env eden.license.env
docker run -d --name eden --restart unless-stopped \
  --env-file eden.runtime.env \
  --env-file eden.license.env \
  --publish 127.0.0.1:8000:8000 \
  --publish 127.0.0.1:6200:6200 \
  --volume eden-data:/var/lib/eden \
  "$EDEN_IMAGE"

Port 8000 is the management API. Port 6200 is reserved for the private Redis listener used in the migration walkthrough. Creating a listener in Eden does not publish a Docker port automatically. These bindings are local to the host; use a private network or authenticated tunnel for remote clients. Backend hostnames must be reachable from inside the container: its localhost refers to Eden, not your host or Redis server.

Run exactly one Eden process against eden-data. Keep both environment files and this volume. The gateway/node identity is derived from the issued license; do not replace it with an unrelated random node UUID. An ordinary image upgrade uses the existing credential rather than obtaining a replacement credential. See upgrade and rollback.

Eden validates the credential with the license server before admitting traffic, then sends periodic heartbeats. Expired, suspended, revoked or stale required licenses block application traffic. Container environment variables are fixed when it is created: to change the credential on an existing deployment, obtain the replacement file, update its secret configuration and recreate the container with the same persistent volume and deployment identity. docker restart alone does not load changed environment-file values.

For an offline license, use an image qualified for offline validation and the authority-issued signed lease and trust files. License validation mode is separate from image flavor. Mount its anti-rollback state persistently and follow the matching offline deployment guide supplied with that qualified image. An online credential or a CLI download session cannot replace that lease.

Offline licenses can be allocated before a host exists. On the target host, prepare its node/deployment identity and signed setup request, activate the allocation from Licenses in the dashboard, and import the returned lease. See offline license setup for the host helper, recovery procedure and persistent-state requirements. Image downloads require an activated allocation and a matching entitlement.

Active trial licenses use the normal eden login and eden image pull flow when their current entitlement covers the selected image. Downloading does not extend a trial or change its runtime usage allowance.

Check the running image using HTTP or the CLI

The running service exposes health and readiness independently of the customer dashboard. /health reports process health; /ready reports whether the configured service can admit traffic, including required license validation. A ready response is an admission check, not proof that an organization, endpoint or migration has been persisted.

curl --fail http://127.0.0.1:8000/health
curl --fail http://127.0.0.1:8000/ready

The CLI can query the same operational API using the running Service's origin:

EDEN_CLI_SERVICE_URL=http://127.0.0.1:8000 eden api request GET /ready
EDEN_CLI_SERVICE_URL=http://127.0.0.1:8000 eden api request GET /api-docs/openapi.json

The runtime reads its credential at startup and calls the licensing authority directly. The CLI's browser login grants image downloads, while your running Service has its own authentication and license configuration. For authenticated Service commands, create a Service context and inspect eden context --help and eden login --help for the supported Service login options.

Connect your first database

The following walkthrough requires an image that includes the organization, authentication and endpoint APIs. Check the running image's OpenAPI document for these operations; the available APIs depend on the published image and its features. It also requires curl, jq, the organization creation token from your private runtime configuration, and a disposable Redis endpoint reachable from Eden. Use HTTPS for a deployed service; localhost HTTP below assumes a private host or tunnel.

Create an organization and log in

Use a new organization ID for this exercise. Supply the bootstrap token from your secret manager and choose an administrator password without printing it:

set -euo pipefail
export EDEN_ORIGIN='http://127.0.0.1:8000'
export EDEN_ORG_ID='quickstart'
export EDEN_ADMIN_USER='admin'
read -r -s -p 'Organization creation token: ' EDEN_NEW_ORG_TOKEN
printf '\n'
read -r -s -p 'New administrator password: ' EDEN_ADMIN_PASSWORD
printf '\n'
jq -n --arg id "$EDEN_ORG_ID" --arg user "$EDEN_ADMIN_USER" \
  --arg password "$EDEN_ADMIN_PASSWORD" \
  '{id:$id,super_admins:[{username:$user,password:$password}]}' \
  | curl --fail --silent --show-error \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $EDEN_NEW_ORG_TOKEN" \
      --data-binary @- "$EDEN_ORIGIN/api/v1/organizations"

EDEN_TOKEN=$(curl --fail --silent --show-error --request POST \
  -H "X-Org-Id: $EDEN_ORG_ID" \
  --user "$EDEN_ADMIN_USER:$EDEN_ADMIN_PASSWORD" \
  "$EDEN_ORIGIN/api/v1/auth/login" | jq -er '.token')
export EDEN_TOKEN
unset EDEN_ADMIN_PASSWORD EDEN_NEW_ORG_TOKEN

Organization creation returns a top-level id and uuid; login returns a top-level token. There is no data.token wrapper. Keep the bearer private. Use least-privilege users/agents for applications after bootstrap.

Verify the organization and node

After login, read the organization and the live node inventory:

curl --fail --silent --show-error -H "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/organizations" | jq .
curl --fail --silent --show-error -H "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/ha/deployment/nodes" | jq .

The organization must be the one you created, and the single-container inventory must identify your running node. Keep the organization and node UUIDs with your deployment record. A missing node or database is locked in startup logs is a deployment failure even if /ready succeeds; use embedded database recovery.

Register Redis

This example assumes an isolated Redis server without authentication or TLS. For a production backend, set its credential tiers and trusted TLS configuration using the Redis endpoint guide. Replace the target host with one resolvable and reachable from the Eden process:

curl --fail --silent --show-error \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $EDEN_TOKEN" \
  -H 'Idempotency-Key: quickstart-create-cache-001' \
  "$EDEN_ORIGIN/api/v1/endpoints" \
  --data '{
    "endpoint":"cache",
    "kind":"Redis",
    "config":{"target":{"host":"redis.internal.example","port":6379},
              "read_credentials":{},"write_credentials":{}}
  }'

A synchronous success returns {"id":"cache","uuid":"..."}. In an HA control deployment, a protected mutation can return 202 with an operation_url; observe that operation and endpoint activation before querying. The idempotency header applies to that control path, not to arbitrary data writes.

Write and read a value

REST endpoint operations use a request object and a typed type discriminator:

curl --fail --silent --show-error \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/endpoints/cache/write" \
  --data '{"request":{"type":"Set","key":"eden:quickstart","value":"hello"}}'

curl --fail --silent --show-error \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/endpoints/cache/read" \
  --data '{"request":{"type":"Get","key":"eden:quickstart"}}'

Check that the returned Redis response represents OK and then hello. Endpoint responses are protocol-specific; inspect the live response schema rather than assuming every endpoint returns a SQL-style rows array.

Check persistence before using customer data

Use the disposable Redis key above as a witness. During an idle maintenance window, restart the container without changing its files or volume:

docker restart --time 180 eden
curl --fail --silent --show-error http://127.0.0.1:8000/ready

If the process is still starting, repeat the read request with a bounded wait; do not recreate the organization. Repeat the organization/node reads and the Redis GET above. Their identities and the returned hello value must remain unchanged. The organization/endpoint reads check control-state persistence; the Redis value checks the configured backend data path. Production backups need a separate verified restore test.

Migrate Redis

Continue with the guided Redis migration for source/target registration, the private listener, preparation, explicit execution approval, live writes, cutover and terminal completion. Start with disposable backends and the same image/profile you will deploy. Finish active migrations before routine upgrades; an interrupted copy can require target reconciliation and a new authorized attempt after restart.

Connect PostgreSQL

PostgreSQL uses a shared target and separate permission-tier credentials. Supply private values through your normal secret/configuration process:

{
  "endpoint": "mydb",
  "kind": "Postgres",
  "config": {
    "target": {"host": "postgres.internal.example", "port": 5432, "database": "app"},
    "read_credentials": {"username": "app_reader", "password": "<reader-secret>"},
    "write_credentials": {"username": "app_writer", "password": "<writer-secret>"}
  }
}

POST this resource to /api/v1/endpoints. A read request to /api/v1/endpoints/mydb/read can use:

{"request":{"type":"SimpleQueryReadOnly","query":"SELECT 1 AS connected"}}

The corresponding write operation uses an allowed write input type such as Execute; see PostgreSQL for typed parameters and output. A PostgreSQL write_conn.url object is not the current central endpoint configuration format.

Inspect the API and continue

Fetch /api-docs/openapi.json or open /swagger-ui/ when your image includes OpenAPI. See discovery and queries for partitions, jq queries and build limitations.

Continue with First steps, reliable clients, telemetry, and backup/restore. For failed requests, use Recovery runbooks; do not retry an uncertain write without determining its outcome.