aispace-client

<p align="center">
  <img src="assets/logo.svg" width="112" height="112" alt="aispace logo">
</p>

<h1 align="center">aispace</h1>

<p align="center">
  <strong>Secure temporary file sharing for AI agents and humans.</strong><br>
  A scriptable CLI with expiring links, predictable JSON, and optional local age encryption.
</p>

<p align="center">
  <a href="https://aispace.sh">Website</a> ·
  <a href="https://aispace.sh/docs">Documentation</a>
</p>

<p align="center">
  <a href="https://github.com/aispace-sh/aispace-client/releases/latest"><img src="https://img.shields.io/github/v/release/aispace-sh/aispace-client?style=flat-square&color=FFD700" alt="Release"></a>
  <a href="https://github.com/aispace-sh/aispace-client/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/aispace-sh/aispace-client/ci.yml?branch=main&style=flat-square&label=Go%20CI" alt="Go CI"></a>
  <img src="https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.26+">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
</p>

<p align="center">
  <img src="assets/demo.gif" width="760" alt="Example terminal session uploading a report and receiving an expiring aispace link">
</p>

[aispace.sh](https://aispace.sh) is a bot-friendly file drop for outputs that are too large,
structured, or temporary for chat. The open-source client is deliberately easy to automate: one
binary, stable exit codes, streaming uploads, and share URLs printed on a predictable final line.

- **Built for agents:** stable JSON on supported commands, documented errors, stdin support, and
  explicit noninteractive flags for automation. Secret-bearing handoff commands remain interactive.
- **Short-lived by design:** file expiration, separately expiring links, revocation, and optional
  per-link download caps.
- **Private when needed:** sealed asynchronous transfers encrypt filenames, file metadata, and
  content locally; their master key never reaches aispace. The existing age X25519 flow remains
  available for recipient-key workflows.

Sealed transfers, agent identities, device pairing, and adaptive durable-first intent are
experimental surfaces. Ordinary uploads and durable R2 storage continue to work alongside them.

The hosted service is operated separately. This repository contains the client, agent skill, and
integration examples—not the server, billing system, deployment configuration, or customer data.

## Try it in 60 seconds

Install the latest release:

```sh
curl -fsSL https://aispace.sh/install.sh | sh
```

Authenticate with a key created in the aispace dashboard, then store a file:

```sh
aispace login --key ask_...
aispace upload report.pdf --json
```

On a Pro account, add a separately expiring public handoff:

```sh
aispace upload report.pdf --link --link-expires 1h --max-downloads 1
```

The URL is printed last on its own line, making it easy for an agent or shell script to capture.
Add `--json` for a stable machine-readable response. An abridged response looks like:

```json
{"file":{"id":"...","name":"report.pdf"},"link":{"url":"https://aispace.sh/d/...","expires_at":1757003600}}
```

Other installation channels:

```sh
npm install -g @aispace-sh/cli
brew install aispace-sh/tap/aispace
go install github.com/aispace-sh/aispace-client@latest
```

Pin the shell installer with `AISPACE_VERSION=v1.2.3`. Release binaries support macOS, Linux, and
Windows on amd64 and arm64. The shell installer supports macOS and Linux; use npm on Windows.

<div align="center">
  <a href="https://x.ai/bot/suv5xSPPbQmzi02LF7Z9Z">
    <img src="assets/grok-bot-mark.svg" width="96" height="96" alt="Grok Bot">
  </a>
  <h3>Using Grok Bot?</h3>
  <p>Give Grok Bot a fast, bot-friendly way to share files with aispace.</p>
  <p>
    <a href="https://x.ai/bot/suv5xSPPbQmzi02LF7Z9Z"><strong>Add the aispace bot to Grok Bot →</strong></a>
  </p>
</div>

---

## Give aispace to an agent

The repository includes a reusable Codex-compatible skill. Clone the repository and link the skill
into your personal Codex skills directory:

```sh
git clone https://github.com/aispace-sh/aispace-client.git
mkdir -p ~/.codex/skills
ln -s "$PWD/aispace-client/skills/aispace" ~/.codex/skills/aispace
```

Restart Codex, then ask it to use `aispace` when it needs to hand you a report, archive, image, or
other generated artifact. The skill defaults to account-private storage unless you request a public
link, prefers short expirations, and treats encryption identities as credentials.

### Model Context Protocol (MCP)

The native CLI also exposes ten typed MCP tools over local stdio. Create a separately scoped bot
key in the dashboard, export it in the environment that launches Codex, and add:

```toml
[mcp_servers.aispace]
command = "aispace"
args = ["mcp", "serve"]
env_vars = ["AISPACE_KEY", "AISPACE_URL", "AISPACE_ALLOWED_ROOTS"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

[mcp_servers.aispace.tools.aispace_create_link]
approval_mode = "prompt"

[mcp_servers.aispace.tools.aispace_revoke_link]
approval_mode = "prompt"

[mcp_servers.aispace.tools.aispace_delete_file]
approval_mode = "prompt"
```

Run `codex mcp list` to verify the connection. The ChatGPT desktop app, Codex CLI, and Codex IDE
extension on the same host share this configuration. Keep the key in a secret store or injected
environment; never put its expanded value in a committed project file or command argument. See
[`docs/CLI.md`](docs/CLI.md#mcp-server) for Claude Code and generic-host examples.

For custom agent runtimes, [`docs/LLM_USAGE.md`](docs/LLM_USAGE.md) includes a system-prompt snippet,
OpenAI/Anthropic-compatible tool schemas, and a reference Python handler. See [`examples`](examples)
for runnable shell, CI, and encrypted-handoff recipes.

## Common workflows

```sh
# Upload text from stdin and return an expiring public link (Pro).
echo "hello" | aispace upload - --name note.txt --link --link-expires 1h

# Keep a file available only to this key.
aispace upload secret.txt --private

# Share ciphertext; keep the generated age identity locally.
aispace upload secret.pdf --encrypt --identity-out secret.agekey --link

# Authenticated handoff to another key on the same account—no public URL.
aispace upload notes.md --shared --json

# Sealed multi-file handoff. The URL fragment holds the local decryption secret.
aispace transfer create report.pdf charts.png --sealed --link --expires 1d --max-downloads 1

# Move that sealed transfer to a nearby browser/device with an expiring code.
aispace handoff offer "$TRANSFER_ID"
# On the receiving CLI: aispace handoff receive J7KM-PQRT

# Pin an agent and deliver without exposing a bearer decryption link.
aispace recipient add "$RECIPIENT_INVITATION"
aispace recipient verify research-agent --fingerprint "$RECIPIENT_FINGERPRINT"
aispace transfer create report.pdf --sealed --to research-agent --from my-agent --expires 7d
aispace inbox receive "$DELIVERY_ID" --yes

# Paste the link interactively, inspect its private manifest, then decrypt and verify.
aispace transfer receive

# Receive, manage, and revoke.
aispace ls --json
aispace download <file_id> --output ./file
aispace download <file_id> --output ./file --verify   # check the recorded SHA-256
aispace link <file_id> --expires 30m --max-downloads 1
aispace revoke <link_id>
aispace rm <file_id>
```

Follow [`docs/SECURE_HANDOFFS.md`](docs/SECURE_HANDOFFS.md) for sealed bundles, trusted agent
inboxes, device pairing, adaptive R2 fallback, and recovery. The complete command reference is in
[`docs/CLI.md`](docs/CLI.md); the HTTP contract is in [`docs/API.md`](docs/API.md).

`upload` accepts `--name`, `--expires`, `--content-type`, `--sha256`, `--link`, `--link-expires`,
`--max-downloads`, `--private`, `--shared`, `--encrypt`, `--recipient`, and `--identity-out`.
Uploads stream from disk. Encrypted uploads use age X25519 locally and store ciphertext as
`<name>.age`; the secret identity is never sent to the API.

`transfer create` uses `aispace-sealed-v1`: AES-256-GCM authenticated chunks and an encrypted
manifest support multiple files, ranged retry, and a verified receipt. `transfer receive` accepts
the secret from its prompt, `--token-file`, or `AISPACE_TRANSFER_TOKEN`; avoid putting a full
fragment link or token in a process argument on shared systems.

`transfer create --json` omits bearer links and tokens unless `--include-secret` is explicit, and
secret-inclusive JSON must be redirected rather than written to a terminal. `handoff encode`
likewise accepts the protected prompt, `--token-file`, or `AISPACE_TRANSFER_TOKEN`.

With `--json`, errors also remain structured and are written to stderr. `upload --link --json`
returns `{"file": File, "link": ShareLink}`; encrypted uploads add an `"encryption"` object.

## Configuration

Precedence: flag > environment > config file > default.

| Setting | Flag | Env | File key | Default |
|---|---|---|---|---|
| API key | `--key` | `AISPACE_KEY` | `key` | — |
| Server | `--url` | `AISPACE_URL` | `url` | `https://aispace.sh` |

`AISPACE_AGE_IDENTITY` supplies a decryption identity when `decrypt --identity-file` is omitted.
It is deliberately not accepted as a command-line value.

Config file: `$XDG_CONFIG_HOME/aispace/config.json` (default `~/.config/aispace/config.json`), written with
mode 0600. A warning is printed if the file is readable by others. `AISPACE_CONFIG` overrides the path.

Durations (`--expires`, `--link-expires`) accept Go syntax plus a `d` suffix: `30m`, `24h`, `7d`, `1d12h`,
or a bare number of seconds. Omitting them uses the server defaults (7 days for files, 1 hour for
Pro public links).

## File permissions and links

File visibility controls authenticated key access. A public link is a separate capability: creating
one requires a Pro account and makes that one file available to anyone holding the URL.

| File mo