Skip to main content

MemoryStore quickstart

In about five minutes you will create a MemoryStore instance, save its password (shown exactly once), watch it become ready, check live stats, and run PING/SET/GET against it.

Before you begin​

The platform is in alpha and there is no public API hostname yet. Reach the MemoryStore API through an endpoint your administrator gives you, or let the CLI port-forward for you. Set up your shell:

export CAI_MEMORYSTORE_API="http://localhost:18081"  # your admin-provided or port-forwarded endpoint
export TOKEN="$CAI_TOKEN"                            # cached by 'platformctl login'
export PROJECT="00000000-0000-0000-0000-000000000000"  # your project UUID
export MS="$CAI_MEMORYSTORE_API"
Prefer clicking?

The console offers the same flow under Data services → MemoryStore in your project, including a copy-once credentials dialog and an option to stash the password straight into your project's Secrets. The CLI is read-only for MemoryStore (list, get, stats); creating instances happens through the API or the console.

Step 1: Create an instance​

We create a small cache-style instance. Because this one is a cache, we override the default eviction policy with allkeys-lru (evict the least-recently-used keys when full) — the default noeviction would make writes fail once memory fills.

curl -sX POST "$MS/v1/projects/$PROJECT/memorystores" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"cache","size_class":"small","maxmemory_policy":"allkeys-lru"}'

You should see (HTTP 201):

{"memorystore":{"name":"cache","state":"Unknown","size_class":"small",...},
 "credential":{"username":"default",
   "password":"<24-random-bytes>",
   "uri":"redis://:<password>@ms-cache.cai-p-<short>.svc.cluster.local:6379"},
 "note":"This is the only response that contains the password. Later reads return the name of the Secret holding it, never the value. The instance is still provisioning; poll until state is Ready before connecting."}

The create response reports state as Unknown, not Provisioning. That is deliberate: the instance was created a millisecond ago and nothing has looked at it yet, so the API reports the truth rather than guessing at progress. Read it again a moment later and you will see Provisioning, then Ready.

Copy it now

This is the only time the API will ever show you the password. Every later read returns the name of the Secret that holds it — never the value. Save the credential block somewhere safe before moving on. If you lose it, an admin can mint a new one with the rotate-credential endpoint.

export MS_PASSWORD="<the password from the response>"

Step 2: Wait for it to be ready​

platformctl memorystore get cache

You should see (usually within ~15 seconds):

NAME   SIZE_CLASS  STATE  READY
cache  small       Ready  yes

What failure looks like​

Ask for stats before the instance is provisioned and you get a 409 with a plain-English explanation:

{"error":"this memorystore is not provisioned yet; wait for it to report Ready, then read its stats","request_id":"..."}

Step 3: Check live stats​

Once Ready, the platform can read live server statistics for you — no connection needed on your side:

platformctl memorystore stats cache

You should see a key/value table including lines like:

used_memory_human      1.00M
maxmemory_policy       allkeys-lru
connected_clients      1
db_keys                0
uptime_in_seconds      42

These are point-in-time values read directly from the running instance — a snapshot, not a time series.

Step 4: Connect and run PING, SET, GET​

The instance is private: it has no public address, and by default it is reachable only from workloads running in your project (or optionally from your Crusoe VPC — see Connect from workloads). From any workload in your project, with redis-cli available:

redis-cli -h ms-cache.cai-p-<short>.svc.cluster.local -p 6379 -a "$MS_PASSWORD" PING

You should see:

PONG

Now a round trip:

redis-cli -h ms-cache.cai-p-<short>.svc.cluster.local -p 6379 -a "$MS_PASSWORD" SET greeting "hello"
redis-cli -h ms-cache.cai-p-<short>.svc.cluster.local -p 6379 -a "$MS_PASSWORD" GET greeting

You should see:

OK
hello

Replace <short> with your project's short identifier — it appears in the uri field of the create response, so the connection string you saved in step 1 already has the exact hostname.

Clean up​

Deleting an instance destroys it and its data volume. This is not reversible, and it requires the project admin role.

curl -sX DELETE "$MS/v1/projects/$PROJECT/memorystores/cache" \
  -H "Authorization: Bearer $TOKEN"

You should see (HTTP 202):

{"name":"cache","resource_path":"projects/<short>/memorystores/cache","state":"Deleting",
 "note":"The instance and its data volume are being reclaimed. This is not reversible."}

Next steps​

  • Connect from workloads — the credential Secret, agents and functions, and the VPC TLS endpoint.
  • Use with agents — where agent sessions live (spoiler: not in this instance).
  • API reference — every field on create, including persistence and external exposure.