Docs · Quickstart

From clone to connector in four commands

Requires Rust 1.97.1 or newer and Git. No Node.js runtime and no npm install at any point.

Step 01

Build

    
          $ git clone https://github.com/Philippwolf/OMAApp.git
        
          $ cd OMAApp
        
          $ cargo build --release
        
          $ cp config.example.json config.local.json

The binary is target/release/omas. To put it on your PATH, runcargo install --path . instead.

Step 02

Approve a repository

Nothing is reachable until you add it. The mode you choose here is enforced by the server, not by the model.

    
          $ omas add ~/Dev/api --mode read
        
          $ omas list
        
          $ omas check

--mode read— bounded, non-mutating
Bounded reads
Bounded repository reads and search. Writes stay disabled.
- Tree, search, and bounded file reads
- Policy explanation before you attempt an operation
- Bounded images and multi-file reads
--mode write— mutating but contained
Contained writes
Everything in read, plus policy-checked file writes subject to denied paths, size limits, symlink checks, and secret scanning.
- Repo-relative file writes
- Hard denied-path and secret-value rejection
- Configured byte and path limits enforced
--mode ship— local history and destructive operations
Local cleanup
Everything in write, plus deletion of generated, untracked artifacts under an explicit path list.
- Untracked cleanup under an explicit path list
- Refuses tracked files outright
- Never runs a shell or a Git command

No mode enables arbitrary command execution. Commands are gated separately and stay disabled until configured explicitly.

A non-interactive invocation without --mode defaults toread. Use --allow-non-git only when you intend to approve a directory that is not a Git worktree, and --config to select a config other than config.local.json.

Step 03

Serve

    
          $ omas serve --config config.local.json
        
          listening 127.0.0.1:8787  ·  /mcp  ·  health /health

Equivalent environment configuration: OMAS_CONFIG,OMAS_HOST, and OMAS_PORT. The server refuses to start on a non-loopback address without a public path token.

Step 04

Expose it to your client

Pick the connector flow that matches how long you need the endpoint to live.

    
          $ omas connect
        
          https://<id>.ngrok.app/t/<random-token>/mcp

Paste that exact URL into your MCP client as the connector Server URL — in ChatGPT that is Developer Mode. For a longer-lived private setup, useomas connect-secure with the OpenAI Secure MCP Tunnel, or the Premium relay for a stable URL with no inbound port.

Connection guide Premium relay

Troubleshooting

If something is off

The connector returns nothing: Confirm you pasted the full tokenized path ending in/t/<token>/mcp, not the bare host. Check/health first.
A write is rejected: Run repo_policy_explain — it reports the effective read, write, and cleanup policy and explains why a given path is allowed or blocked.
The server refuses to start: A non-loopback bind is refused without a public path token, and refused outright when command execution is enabled. Run omas doctor.

From clone to connector in four commands

Build

Approve a repository

Bounded reads

Contained writes

Local cleanup

Serve

Expose it to your client

If something is off