Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion .github/scripts/check-root-directory-entries.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ function readRootEntries(sha) {
return stdout.split('\0').filter(Boolean)
}

// Why: the Cloud workspace import is the one reviewed root addition; it stays
// listed until it lands on main, after which the base tree carries it.
const REVIEWED_ROOT_ENTRIES = new Set(['cloud'])

function checkRootDirectoryEntries(argv) {
if (argv.length !== 2) {
console.error(`Usage: ${process.argv[1]} <base-sha> <head-sha>`)
Expand All @@ -21,7 +25,9 @@ function checkRootDirectoryEntries(argv) {

const [baseSha, headSha] = argv
const baseEntries = new Set(readRootEntries(baseSha))
const blockedEntries = readRootEntries(headSha).filter((entry) => !baseEntries.has(entry))
const blockedEntries = readRootEntries(headSha).filter(
(entry) => !baseEntries.has(entry) && !REVIEWED_ROOT_ENTRIES.has(entry)
)

if (blockedEntries.length === 0) {
console.log('Root directory guard passed: no new root-level files or folders.')
Expand Down
103 changes: 103 additions & 0 deletions .github/workflows/cloud-verify.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
name: Cloud Verify

on:
pull_request:
paths:
- cloud/**
- .github/workflows/cloud-*.yml
push:
branches: [main]
paths:
- cloud/**
- .github/workflows/cloud-*.yml

permissions:
contents: read

concurrency:
group: cloud-verify-${{ github.ref }}
cancel-in-progress: true

defaults:
run:
working-directory: cloud

jobs:
security:
name: Secret scan
runs-on: blacksmith-2vcpu-ubuntu-2204
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Scan Cloud history with Gitleaks
run: >-
docker run --rm
--volume "${GITHUB_WORKSPACE}:/repo:ro"
zricethezav/gitleaks@sha256:cdbb7c955abce02001a9f6c9f602fb195b7fadc1e812065883f695d1eeaba854
git /repo --config /repo/cloud/.gitleaks.toml
--log-opts="--all -- cloud :(glob).github/workflows/cloud-*.yml"

- name: Scan the single-commit Cloud snapshot with TruffleHog
run: >-
docker run --rm
--volume "${GITHUB_WORKSPACE}:/repo:ro"
trufflesecurity/trufflehog@sha256:5dc064868ba7933601b5cbaea6954954d524ddd5dc6222a9667acea70068bf7d
filesystem /repo --no-verification --fail
--include-paths=/repo/cloud/.trufflehog-include-paths.txt
--exclude-paths=/repo/cloud/.trufflehog-exclude-paths.txt

# Compiles the workspace. No Postgres service: nothing here reaches a
# database, and the service container costs ~13s of startup.
build:
runs-on: blacksmith-4vcpu-ubuntu-2204
steps:
- uses: actions/checkout@v4

- uses: pnpm/action-setup@v4
with:
package_json_file: cloud/package.json

- uses: actions/setup-node@v4
with:
node-version: 24

- run: pnpm install --frozen-lockfile
- run: pnpm build
- run: pnpm typecheck

# Runs in parallel with build. `pnpm test` compiles the one workspace
# package it needs through the relay pretest hook, so it does not depend on
# `pnpm build` having run.
test:
runs-on: blacksmith-4vcpu-ubuntu-2204
services:
postgres:
image: postgres:16-alpine
env:
POSTGRES_DB: orca_relay_test
POSTGRES_PASSWORD: relay_test
POSTGRES_USER: relay_test
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U relay_test -d orca_relay_test"
--health-interval 5s
--health-timeout 5s
--health-retries 10
env:
ORCA_RELAY_TEST_POSTGRES_URL: postgres://relay_test:relay_test@127.0.0.1:5432/orca_relay_test
steps:
- uses: actions/checkout@v4

- uses: pnpm/action-setup@v4
with:
package_json_file: cloud/package.json

- uses: actions/setup-node@v4
with:
node-version: 24

- run: pnpm install --frozen-lockfile
- run: pnpm test
3 changes: 2 additions & 1 deletion .oxfmtrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,6 @@
"singleQuote": true,
"semi": false,
"printWidth": 100,
"trailingComma": "none"
"trailingComma": "none",
"ignorePatterns": ["cloud/**"]
}
8 changes: 7 additions & 1 deletion .oxlintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -174,5 +174,11 @@
}
}
],
"ignorePatterns": ["**/node_modules", "**/dist", "**/out", "tests/e2e/.cross-version-checkouts"]
"ignorePatterns": [
"**/node_modules",
"**/dist",
"**/out",
"cloud/**",
"tests/e2e/.cross-version-checkouts"
]
}
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,9 @@ Pair with your desktop app to monitor and steer your agents from your phone.

Want to contribute or run locally? See our [CONTRIBUTING.md](.github/CONTRIBUTING.md) guide.

The relay that pairs the mobile app with a desktop host is also in this repository under
[`cloud/`](cloud/README.md), with a separate pnpm workspace and setup guide.

<a href="https://github.com/stablyai/orca/graphs/contributors">
<img src="https://contrib.rocks/image?repo=stablyai/orca" alt="Orca contributors" />
</a>
Expand Down
15 changes: 15 additions & 0 deletions cloud/.dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
.git/
.github/
.local/
.terraform/
node_modules/
dist/
coverage/
.env
.env.local
.env.local.generated
*.log
*.tfplan
*.tfstate
*.tfstate.*

10 changes: 10 additions & 0 deletions cloud/.editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

24 changes: 24 additions & 0 deletions cloud/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
node_modules/
dist/
coverage/
.turbo/
.local/
.env
.env.local
.env.local.generated
*.log

# Terraform/OpenTofu local state and plans must stay out of git.
**/.terraform/
*.tfstate
*.tfstate.*
*.tfplan
crash.log
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# Local dev signing key + SQLite live under data/ — never commit (contains a
# private key and dev PII). Prod supplies the key via ORCA_CLOUD_SIGNING_KEY_PEM.
data/
7 changes: 7 additions & 0 deletions cloud/.gitleaks.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[extend]
useDefault = true

[[allowlists]]
description = "Explicit Relay test signing key"
regexTarget = "secret"
regexes = ['''^test-assignment-key-with-at-least-32-bytes$''']
2 changes: 2 additions & 0 deletions cloud/.node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
24

3 changes: 3 additions & 0 deletions cloud/.npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
engine-strict=false
package-manager-strict=true

1 change: 1 addition & 0 deletions cloud/.trufflehog-exclude-paths.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
(^|/)cloud/apps/relay/src/postgres-idle-client-error\.test\.ts$
2 changes: 2 additions & 0 deletions cloud/.trufflehog-include-paths.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
(^|/)cloud/
(^|/)\.github/workflows/cloud-[^/]+\.yml$
50 changes: 50 additions & 0 deletions cloud/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Orca Relay

The relay that connects the Orca mobile app to a desktop host. Phones and
desktops never talk to each other directly: each opens an outbound WebSocket
to a relay cell, the relay pairs the two sessions, and it splices frames
between them. A director assigns hosts to cells and coordinates migrations;
cells carry the user connections.

This directory is an independent pnpm workspace inside the Orca monorepo. Run
its commands from `cloud/`, not the repository root. The source is covered by
the repository's root [MIT license](../LICENSE).

## Packages

- `packages/relay-contract`: the wire contract shared by the relay, the
desktop app, and the mobile app (frame shapes, close codes, admission budgets,
splice state machine).
- `apps/relay`: the relay server. The same image runs as a director or a cell
depending on `ORCA_RELAY_ROLE`.

## Local development

```sh
cd cloud
pnpm install
pnpm build
pnpm test
```

`pnpm test` runs the SQLite-backed suites. Tests that need PostgreSQL run only
when `ORCA_RELAY_TEST_POSTGRES_URL` points at a disposable PostgreSQL 16 or 17
database, for example:

```sh
docker run --rm -d --name orca-relay-pg -e POSTGRES_HOST_AUTH_METHOD=trust \
-e POSTGRES_DB=orca_relay_test -p 55440:5432 postgres:16-alpine
ORCA_RELAY_TEST_POSTGRES_URL=postgres://postgres@127.0.0.1:55440/orca_relay_test \
pnpm --filter @orca-cloud/relay test
docker rm -f orca-relay-pg
```

Configuration is read from environment variables validated in
`apps/relay/src/config.ts`. `ORCA_RELAY_ASSIGNMENT_SIGNING_KEY` (at least 32
bytes) is the only required value; everything else has a local default.

## Deployment

The hosted relay's infrastructure, deployment workflows, and operational tooling
are maintained privately. `Cloud Verify` in this repository builds, typechecks,
lints, tests, and secret-scans the relay on every change under `cloud/`.
25 changes: 25 additions & 0 deletions cloud/apps/relay/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
FROM node:24-alpine AS build
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
COPY packages/relay-contract/package.json packages/relay-contract/package.json
COPY apps/relay/package.json apps/relay/package.json
RUN pnpm install --frozen-lockfile
COPY packages/relay-contract packages/relay-contract
COPY apps/relay apps/relay
RUN pnpm --filter @orca-cloud/relay-contract build && pnpm --filter @orca-cloud/relay build

FROM node:24-alpine AS runtime
ENV NODE_ENV=production
ENV PORT=8080
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY packages/relay-contract/package.json packages/relay-contract/package.json
COPY apps/relay/package.json apps/relay/package.json
COPY --from=build /app/packages/relay-contract/dist packages/relay-contract/dist
COPY --from=build /app/apps/relay/dist apps/relay/dist
RUN pnpm install --prod --frozen-lockfile --filter @orca-cloud/relay...
USER node
EXPOSE 8080
CMD ["node", "apps/relay/dist/index.js"]
35 changes: 35 additions & 0 deletions cloud/apps/relay/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"name": "@orca-cloud/relay",
"private": true,
"version": "0.0.0",
"type": "module",
"main": "dist/index.js",
"scripts": {
"build": "pnpm clean && tsc -p tsconfig.build.json",
"clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
"dev": "tsx watch src/index.ts",
"lint": "tsc -p tsconfig.json --noEmit",
"pretest": "pnpm --filter @orca-cloud/relay-contract build",
"start": "node dist/index.js",
"test": "vitest run",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"@hono/node-server": "^1.19.14",
"@orca-cloud/relay-contract": "workspace:*",
"hono": "^4.12.27",
"jose": "^6.1.3",
"pg": "^8.22.0",
"tweetnacl": "^1.0.3",
"ws": "^8.18.3",
"zod": "^3.25.76"
},
"devDependencies": {
"@types/node": "^24.10.0",
"@types/pg": "^8.20.0",
"@types/ws": "^8.18.1",
"tsx": "^4.21.0",
"typescript": "^5.9.3",
"vitest": "^4.0.8"
}
}
Loading
Loading