Star Office UI: a pixel status board whose bundled art cannot be sold

Python 3.10 is a floor, not a preference, and Flask is the only dependency

The stated environment requirement is Python 3.10+, and the reason given is specific rather than aspirational: the code uses `X | Y` union type syntax, which 3.9 and lower do not support. The project metadata agrees, with requires-python set to >=3.10 in pyproject.toml, and the dependency list contains exactly one entry, flask>=3.0.0. That single dependency is why the install step is one command and why the backend directory carries its own requirements.txt alongside app.py and run.sh. The consequence for an evaluator is that the surface you are taking on is small and readable, but it is not Python-version agnostic: a host pinned to 3.9, which still appears on older embedded and managed machines, cannot run this at all without an interpreter upgrade. The deployment also expects you to create the state file yourself before the first run, because the backend reads state.json rather than inventing state.

# 1) 下载仓库
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI

# 2) 安装依赖（需要 Python 3.10+）
python3 -m pip install -r backend/requirements.txt

# 3) 准备状态文件（首次）
cp state.sample.json state.json

# 4) 启动后端
cd backend
python3 app.py

Once it is running you open http://127.0.0.1:19000 and change states from the command line:

python3 set_state.py writing "正在整理文档"
python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"

State is a file you copy once, and a stale state falls back to idle

There is no database in this design. The initialisation step copies state.sample.json to state.json, and set_state.py writes the current state into it, which is why the file template is checked in next to join-keys.sample.json and runtime-config.sample.json. The same simplicity shows up in the maintenance history: the 2026-03-04 entry for P0 and P1 security hardening lists weak password blocking, a split of the backend into modules, an automatic return of stale states to idle, and a skeleton screen for the first paint. That stale-to-idle rule is the safety net for a file-based design. If whatever was supposed to push a state disappears, the dashboard goes back to idle rather than freezing a character in the middle of a task, so the failure mode is a wrong-looking office rather than a wrong-looking office forever. The consequence for you as a user is that the board is only as honest as the process writing to it.

Six states collapse into three rooms, so the room tells you less than the state

The state list has six members, idle, writing, researching, executing, syncing and error, and each is mapped to an area of the pixel office. Idle goes to the rest area on the sofa. Writing, researching, executing and syncing all go to the same work area at the desk. Error goes to the bug area. That mapping is the interesting part, because four of the six states land in the same place: the floor plan distinguishes standing by, working and broken, and nothing else. The detail is carried by the animation and the speech bubble rather than by where the character is standing. If you are building a wallboard that people glance at from across a room, plan for that: the useful signal at a distance is busy or not busy, and a visitor cannot tell a research pass from a command execution without reading the text.

A join key caps a team at three guests online at once

Multi-agent collaboration runs through join keys, and the mechanism has a default limit worth knowing. On the first backend start, if join-keys.json does not exist, the service generates a runtime one from join-keys.sample.json, containing a sample key such as `ocj_example_team_01`. You can add, edit or delete keys in the generated file, and each key supports at most 3 people online simultaneously by default. The 2026-03-05 maintenance entry adds join key expiry and concurrency control to that list, so the cap is enforced rather than merely advised. A guest then downloads office-agent-push.py and fills in three variables:

JOIN_KEY = "ocj_starteam02"          # 你分配的 key
AGENT_NAME = "小明的龙虾"            # 显示名称
OFFICE_URL = "https://office.hyacinth.im"  # 你的办公室地址

and the script joins the office and pushes state every 15 seconds. Guests can alternatively install frontend/join-office-skill.md as a Skill so an agent configures itself. The consequence is arithmetic: a fourth concurrent guest on one key does not fit, so size your keys for the team you expect.

The code is MIT and the artwork is not, which decides what you can ship

The licensing is split in two and the split is stated in the project description itself. Code and logic are MIT, with a LICENSE file at the root. Art assets are prohibited for commercial use, being for learning, demonstration and exchange only, and the instruction for commercial use is to replace every art asset with your own original material. The guest character animation uses LimeZu's free Animated Mini Characters 2 (Platformer) assets, and the project asks that attribution be kept when redistributing or demonstrating. The repository is candid about how much of the art pipeline exists because of that: convert_to_webp.py, gif_to_spritesheet.py, webp_to_spritesheet.py, resize_map.py and repack_star_working.py sit at the top level, alongside asset-defaults.json and asset-positions.json for placing them. The consequence is a deployment question rather than a legal one. You may read, fork and study all of it, but a product with revenue attached needs different pixels, and the sidebar even manages character, scene and decoration assets as first class objects with dynamic frame sync to avoid flicker.

Public exposure is one tunnel command, and production needs two secrets set by hand

Getting the board off localhost is one command, and the recommended route is a Cloudflare Tunnel:

cloudflared tunnel --url http://127.0.0.1:19000

which returns a `https://xxx.trycloudflare.com` address you can share, with your own domain and a reverse proxy named as the alternative. That ease is exactly why the production notes matter. The first deployment can keep the default configuration, but for production you are told to copy .env.example to .env and set a strong random FLASK_SECRET_KEY and ASSET_DRAWER_PASS. The example file is specific: STAR_OFFICE_ENV=production is what turns on the startup hardening checks, the Flask session secret must be at least 24 characters, and the asset drawer password is required with a recommendation of 8 or more characters and an explicit instruction not to use 1234. The feature list also names sidebar password protection, weak password blocking and session cookie hardening. The optional Gemini image generation key and model default live in the same file, and can alternatively be set in runtime-config.json through the UI.

The Electron pet is experimental, and the manifest version disagrees with the tags

Two loose ends to know before you rely on this. The desktop pet version lives in desktop-pet/ as an Electron wrapper that turns the office into a transparent-window desktop pet, started with `npm install` then `npm run dev` inside that directory; it launches the Python backend itself, points its window at `http://127.0.0.1:19000/?desktop=1`, and lets you override the project and Python paths through environment variables. It is described as an optional experimental feature mainly developed and tested on macOS, and credited to one contributor. The second is versioning: the release tags are v1.0.0 from 2026-03-06 and v0.1.0 from 2026-02-26, while pyproject.toml still declares version 0.1.0. The repository is not archived, but the last push is dated 2026-03-11, so pin to a tag rather than trusting the manifest. The changelog also records why the default port moved from 18791 to 19000, to avoid colliding with the OpenClaw Browser Control port, which is a useful hint if you are running both.

Editorial conclusion

Use it as a personal status board or as a companion to an OpenClaw setup, and expect a weekend of configuration rather than a product. Do not plan to ship it inside something commercial without replacing the artwork first, since the code is MIT but the assets are licensed for learning and demonstration only. Before exposing it, set FLASK_SECRET_KEY to at least 24 random characters and ASSET_DRAWER_PASS to at least 8, copy .env.example to .env, and pin to the v1.0.0 tag rather than to the manifest, which still says 0.1.0.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. ringhyacinth/Star-Office-UI on GitHub