--- name: mist-getting-started description: Connect to Mist, the S3-compatible object store for agents. Use when you first need to store or read files in Mist, check who you are (whoami), get S3 credentials, or verify that Mist works from this machine. license: Apache-2.0 --- # Getting started with Mist Mist is an S3-compatible object store built for agents. You have your own identity (a principal), you own the buckets you create, and other agents reach your data only through grants and roles you give them. Three things to know: 1. **Data is plain S3.** Read, write, list and delete objects with any S3 client. Mist adds no object API. 2. **Credentials are short-lived.** Your identity (a JWT in a token file, or a principal key) is exchanged for S3 keys that last 1 hour by default. The MCP `credentials` tool, the Python SDK and `mist-credentials` do this for you. 3. **Everything else is the Mist control plane**: buckets with owners, grants, roles, run workspaces, change events. As MCP tools, or as SDK calls. ## Configuration Every Mist plugin reads the same environment variables: | Variable | What | |---|---| | `MIST_ENDPOINT` | The one Mist address: S3, STS and the Mist HTTP API, e.g. `https://mist.example.com` | | `MIST_S3_ENDPOINT` | Only if S3 is on a different address than `MIST_ENDPOINT`, e.g. `https://s3.example.com` | | `MIST_IDENTITY_TOKEN_FILE` | A file holding your identity token (JWT). Re-read on every mint, so a rotated token just works | | `MIST_PRINCIPAL_KEY_ID`, `MIST_PRINCIPAL_KEY_SECRET` | Instead of a token: a principal key from your Mist admin | | `MIST_CA_BUNDLE` | Only when the cluster uses a private CA | If a tool answers `NotConfigured` or `IdentityError`, one of these is missing. Ask the user to set it; never invent a token. ## Step 1: who am I MCP: call `whoami`. Python: ```python import os, mist m = mist.Client(ca_bundle=os.environ.get("MIST_CA_BUNDLE")) # endpoints and token file from the environment print(m.whoami()) ``` The reply has `principal` (`issuer` and `id`: give these to another agent so it can grant you access), `owned_buckets`, `rights` (bucket, folder, actions and where each right comes from) and `roles` you may assume. A brand-new identity owns nothing and has no rights. That is normal. Create a bucket first (step 2): an identity with no access at all cannot mint S3 credentials (`AccessDenied` from STS). ## Step 2: a bucket of your own MCP: `create_bucket` with `name`. Python: `m.buckets.create("my-agent-data")`. - Creating buckets needs a create permission from the cluster's admin, usually for a name pattern (for example `team-*`). `403` with rule `create_not_permitted` means exactly that: you have none for this name. Use a name that matches your permission, or ask the user for one, or work in a bucket someone has granted you. - Names are global in the cluster: 3-63 characters, lowercase letters, digits, `-`. Pick something specific (`-`). `409 BucketExists` means the name is taken: choose another. - New buckets start with a whole-bucket expiry rule (30 days by default on a stock cluster): objects are deleted that many days after they were written. `get_bucket` shows the rules. ## Step 3: S3 credentials MCP: call `credentials`. It returns `access_key_id`, `secret_access_key`, `session_token`, `expiration`, `s3_endpoint`, and `env`, the same values as AWS environment variables. With the AWS CLI: ```sh export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=... AWS_REGION=us-east-1 export AWS_ENDPOINT_URL_S3="${MIST_S3_ENDPOINT:-$MIST_ENDPOINT}" # and AWS_CA_BUNDLE="$MIST_CA_BUNDLE" for a private CA aws s3api put-object --bucket my-agent-data --key hello.txt --body ./hello.txt aws s3api list-objects-v2 --bucket my-agent-data ``` In one shell command, pass the values inline (`AWS_ACCESS_KEY_ID=... aws s3api ...`) rather than writing them to a file. Do not echo the secret or the session token back to the user. Python (the SDK mints and refreshes for you, no copying keys): ```python s3 = m.s3() # a plain boto3 client s3.put_object(Bucket="my-agent-data", Key="hello.txt", Body=b"hello") print(s3.get_object(Bucket="my-agent-data", Key="hello.txt")["Body"].read()) ``` **AWS CLI without copying keys (recommended for many commands).** The session token is over 1,000 characters and easy to copy wrongly (`InvalidRequest: invalid token`). With [uv](https://docs.astral.sh/uv/) installed, write an AWS config file that mints by itself through `mist-credentials`. It holds no secret: ```sh cat > mist-aws.config <