Quick start

This guide takes about five minutes. You will install the shadow binary, create a persona for your machine, start Shadow in the foreground and send a request through it.

Install Shadow
Terminal window
curl -fsSL https://raw.githubusercontent.com/Tiny-Bubble-Company/shadow/main/packaging/install.sh | sh
Terminal window
irm https://raw.githubusercontent.com/Tiny-Bubble-Company/shadow/main/packaging/install.ps1 | iex
Terminal window
cargo install --locked --git https://github.com/Tiny-Bubble-Company/shadow shadow-cli
The install script downloads a release binary when one exists for your platform and otherwise builds from source with cargo. It never changes system settings. See Installation for Docker and service setups.

Create the persona, vault key and local CA

shadow init --org "Acme GmbH"

--org names your organisation. Shadow protects it (and the bare name Acme) and maps it to the persona’s company. You can pass --org several times, and --region JP to choose where the persona lives.

◆ Persona — what AI providers see
  company         Xinghe Technology Co., Ltd. (xinghe.cn)
  person          Ying Chen <ying.chen@xinghe.cn>
  location        Chengdu, China · Asia/Shanghai · zh-CN
  user id         user-941ea3e72322
  username        yingchen
  hostname        xinghe-srv-11
  colleagues      Tao Zhu, Hui Yang, Lei Li, Yong Xu

Your persona will differ: it is generated randomly once and then kept.

Try masking offline

echo "Ticket from jane@acme.com (Acme GmbH): card 4111 1111 1111 1111 declined, logs in /Users/jdoe/src" | shadow mask

Ticket from tsun@xinghe.cn (Xinghe Technology Co., Ltd.): card 4261 8002 0172 9224 declined, logs in /Users/jwang/src

Pipe the output into shadow unmask and you get the original back. Nothing is sent anywhere by these commands.

Start Shadow
Terminal window
```
shadow run
```
Shadow listens on 127.0.0.1:8877 as both an HTTPS proxy and a gateway. Leave it running and open a second terminal.
Send a protected request

The quickest path is gateway mode, which needs no certificate setup. Point the OpenAI base URL at Shadow:
Terminal window
```
curl http://127.0.0.1:8877/gw/openai/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Summarise in one line: jane@acme.com from Acme GmbH says her card was declined."}]}'
```
The provider receives the persona’s email and company. The response you get back contains jane@acme.com and Acme GmbH. With shadow run in the foreground, the log shows how many values were replaced for each request, never the values themselves.

Most SDKs read a base URL from the environment, so existing tools often need just one variable:
Terminal window
```
export OPENAI_BASE_URL=http://127.0.0.1:8877/gw/openai/v1
export ANTHROPIC_BASE_URL=http://127.0.0.1:8877/gw/anthropic
```

Verify

shadow status            # proxy health, persona, vault size, CA fingerprint
shadow identity          # the persona providers see
shadow vault stats       # how many values are protected, by kind
shadow scan prompt.txt   # what Shadow would replace in a file, without changing it

Cover more tools: proxy mode

Gateway mode works for anything that accepts a base URL. To cover tools that don’t, such as IDE extensions, desktop apps and scripts that call a supported AI API and honour HTTPS_PROXY, use Shadow as an HTTPS proxy. That needs the local CA to be trusted once:

shadow install            # dry run: prints every step it would take
shadow install --apply    # background service + CA trust + env file

Then add the printed environment (also written to <data dir>/env.sh) to your shell profile:

export HTTPS_PROXY=http://127.0.0.1:8877
export NO_PROXY=localhost,127.0.0.1

Only known AI hosts are decrypted. Everything else passes through a blind tunnel, which also means AI web apps such as chatgpt.com in a browser are not masked. Details in Proxy mode.

Detectors find structured values on their own. Add the names they cannot know about, such as codenames, customers and people:

shadow terms add "Project Falcon" "org:Globex" "person:Jane Doe"

What next

Choose an integration mode for each of your tools.
Read about intent-aware policy before using agents with tools.
Review the configuration reference.