---
name: ramo-trial
description: Create and use a free 1 GB Ramo S3 trial bucket
---

# Ramo trial skill

Ramo is S3-compatible storage (https://s3-trial.ramo.io). This skill creates a free trial
(1 GB, 365 days) and performs file operations on it.
If you can execute shell commands, run these steps directly; if you cannot,
walk the user through them by hand instead.

## 1. Create the trial (no auth)

```
curl -s -X POST https://api.ramo.io/api/portal/trials -H 'content-type: application/json' -d '{"name": "<label>"}'
```

The response contains `endpoint`, `bucket`, `access_key`, `secret_key` (shown once),
`portal_token` (Bearer token for the management API), `quota_bytes`, `expires_at`, and
a `limits` object (the same figures `GET https://api.ramo.io/api/portal/trials/limits` returns, see step 5).
Store the keys immediately; the secret is not retrievable again.

Errors come back as `{"errors":{"detail":"..."}}` with an HTTP status: 400 means
the name field must be a string, and 429 means you've hit the per-IP signup cap.
The edge counts every request against that cap, not just successful signups, so
retrying a malformed call still burns it; fix the request instead of spamming it.
503 covers two cases: trials disabled (terminal for now, try later) and trial
creation failed (safe to retry once). If the host does not resolve, the connection
times out, or it is otherwise unreachable, treat it as a platform outage: do not
retry in a loop, it is not one of the retryable cases above.

## 2. Configure access

Two equally valid paths depending on what the environment has installed. Path-style
addressing is the supported and documented mode either way.

**With aws-cli:**

```
aws configure set --profile ramo-trial aws_access_key_id <access_key>
aws configure set --profile ramo-trial aws_secret_access_key <secret_key>
aws configure set --profile ramo-trial region us-east-1
aws configure set --profile ramo-trial s3.addressing_style path
```

A dedicated named profile, never the default one, so the trial can never clobber
the caller's existing AWS config. Every subsequent command carries
`--profile ramo-trial`.

**Without aws-cli** (the common case for a sandboxed agent with no package-install
rights): use the helper script instead, `curl -fsSL https://ramo.io/ramo.sh | sh -s -- signup`. This is a first-class
path, not a degraded fallback: `signup | put | get | ls | rm | usage` cover every
operation below without aws-cli. Its SigV4 signer briefly exposes the secret key in
local process listings (`ps`, `/proc/<pid>/cmdline`) while signing each request; on a
shared machine, install aws-cli instead (`pip install awscli`), since it keeps
credentials in the environment and has no such exposure.

Either way, credentials persist to `$HOME/.config/ramo/credentials`
(`RAMO_CRED_FILE` to override) and the helper script writes its own aws-cli config
alongside it (`RAMO_AWS_CFG_FILE` to override, defaults next to the credentials
file). The API base is `https://api.ramo.io` (`RAMO_API` to override). To keep
everything inside a sandbox directory, set `RAMO_CRED_FILE` (and `RAMO_AWS_CFG_FILE`
if also using aws-cli) before running any `ramo.sh` command.

The piped one-liner (`curl ... | sh -s -- signup`) self-installs: since it runs
with no `ramo.sh` file on disk, signup downloads its own source to `./ramo.sh`
before calling the signup API, from `https://ramo.io/ramo.sh` (`RAMO_SCRIPT_URL` to
override, for staging or a remapped host). Running signup from an already
installed `ramo.sh` skips this; every other subcommand is unaffected either way.

## 3. File operations

```
aws s3 cp <file> s3://<bucket>/ --profile ramo-trial --endpoint-url https://s3-trial.ramo.io
aws s3 ls s3://<bucket>/ --profile ramo-trial --endpoint-url https://s3-trial.ramo.io
aws s3 cp s3://<bucket>/<key> . --profile ramo-trial --endpoint-url https://s3-trial.ramo.io
aws s3 rm s3://<bucket>/<key> --profile ramo-trial --endpoint-url https://s3-trial.ramo.io
```

Or the equivalent helper-script subcommands: `put <file> [key]`, `get <key> [dest]`,
`rm <key>`. `ramo.sh ls --json` emits `{"objects": [...], "truncated": <bool>}`
instead of the rendered table, for programmatic use. Re-running `signup` requires
`--force`, which protects any existing stored credentials from being overwritten by
accident.

Uploads are capped at roughly 100 MB per request (Cloudflare's
proxied body limit on the trial tunnel path). `aws s3 cp` stays under this
transparently via its own automatic multipart upload; the no-aws-cli fallback
(`ramo.sh put`) sends a single PUT per call with no multipart support, so split
files larger than ~100 MB before uploading them that way.

The signup response's `endpoint` field (see step 1) is what every command above
actually talks to; it is persisted into the credentials file rather than printed
anywhere else, so an agent running against a remapped or staging-style host must
read it from there, not assume the illustrative `https://s3-trial.ramo.io` shown above.

## 4. Listing display (always render listings this way)

```
<bucket> · <n> objects · <used (this bucket)> / 1 GB trial quota

| Object | Size | Modified |
|--------|------|----------|
| <key> | <human size> | <YYYY-MM-DD HH:MM UTC> |
```

This header line is bucket-scoped usage; the trial-wide aggregate across every
bucket in the trial is at `GET https://api.ramo.io/api/portal/usage`. Keys containing
`|` must be escaped as `\|` so the markdown table doesn't break. Without aws-cli,
`ramo.sh ls` fetches a single page (the first 1000 keys) and marks the listing
truncated instead of paginating; aws-cli itself always paginates fully.

## 5. Management API

Usage, more buckets, rotation: Bearer `portal_token` against https://api.ramo.io/api/portal/*
(OpenAPI: https://api.ramo.io/api/openapi). Limits: 1 GB total per trial,
expires after 365 days, max 3 buckets per trial.
Signups are capped at 5 per IP per day; the edge answers
over-cap signups with a JSON 429, so back off rather than retry immediately. Data-plane
S3 calls carry their own `X-Ratelimit-*` response headers; that is a separate budget
from the signup cap above, not the same one showing up twice. Do not throttle S3
calls against the signup limit. A trial over quota gets its writes denied at the
storage layer and 403s on new buckets, but credentials can still be minted or rotated
so you can delete data and get back under quota; access restores on the watchdog's
next pass.
Fetch the same limit figures programmatically, no auth required (useful for checking
before assuming the prose above is still current):

```
# quota, bucket cap, ttl, signup cap — no auth needed
$ curl -s https://api.ramo.io/api/portal/trials/limits
```

Docs: https://docs.ramo.io/trial