Lewati ke konten

Menyiapkan lingkungan

Lingkungan adalah stack berjalan milik satu space: layanan yang dibutuhkan sebuah branch, terisolasi dari semua space lain, terlihat di bilah sisi, dan dapat dijangkau agen. Pull request juga mendapatkannya, karena PR sudah memiliki space sendiri.

Admin ruang kerja menulis definisi satu kali. Anggota lalu menekan Mulai di bagian Lingkungan pada bilah sisi space atau PR. Definisi disimpan di basis data ruang kerja, sehingga branch fitur tidak pernah mengubah apa yang dijalankan Control Center, meskipun alat tetap menjalankan kode branch tersebut.

  1. Buka Pengaturan → Ruang kerja → Lingkungan. Hanya admin ruang kerja yang dapat mengubah definisi, dan hanya pemilik server yang dapat menyimpan definisi yang berjalan di host server (lihat Siapa yang dapat menyimpan apa).
  2. Klik Definisi baru, lalu Definisi kosong atau Draf dari repo. Draf memindai repo untuk file compose, Procfile, dan skrip package.json, lalu Anda meninjau hasilnya.
  3. Isi formulir, atau gunakan tab JSON. Contoh di halaman ini adalah JSON tersebut.
  4. Klik Jalankan pengujian. Ini memulai lingkungan sekali pakai, menunggu sampai siap, lalu menghancurkannya.

Saat menyimpan, definisi diperiksa dengan ketat. Field yang tidak dikenal, nilai dengan tipe yang salah, atau pilihan yang salah eja ditolak, beserta path-nya dan nama valid terdekat, misalnya repos.app.requird: Unknown field. Did you mean "required"?. $schema di tingkat teratas diizinkan.

Untuk menyimpan definisi di repo, gunakan Tautkan file repo. Control Center membaca file hanya dari branch default dan hanya menjalankan versi yang disetujui: oleh admin ruang kerja, atau oleh pemilik server ketika definisi berjalan di host. Versi yang lebih baru menampilkan Pembaruan tersedia dan tidak mengubah apa pun sampai disetujui.

Sebuah definisi lingkungan dapat menjalankan perintah di host server sebagai pengguna server itu sendiri. Itu keputusan pemilik server, bukan peran ruang kerja:

  • Sebuah definisi berjalan di host ketika ia memiliki penempatan host, pemeriksaan yang menjalankan perintah, atau tugas provision atau archive. Tugas-tugas itu berjalan di worktree space di host, apa pun penempatannya.
  • Hanya pemilik server yang dapat menyimpan atau menyetujui definisi yang berjalan di host. Itu termasuk menyetujui versi baru dari file repo yang ditautkan. Admin ruang kerja yang mencobanya melihat “Hanya pemilik server yang dapat menyimpan atau menyetujui lingkungan yang berjalan di host server. Admin ruang kerja dapat menggunakan lingkungan yang berjalan di rig.”
  • Admin ruang kerja dapat menyimpan dan menyetujui definisi yang sepenuhnya berjalan di rig: "placement": "rig", tanpa perintah pemeriksaan dan tanpa tugas provision atau archive.
  • Anggota memulai, menghentikan, dan menggunakan lingkungan dalam kedua kasus.
  • Definisi yang berjalan di host hanya berjalan setelah pemilik server saat ini menyimpan atau menyetujuinya. Server mencatat persetujuan itu sendiri dan memeriksanya sebelum setiap mulai, pemeriksaan, tugas, dan sinkronisasi kepala pull request. Definisi yang belum disetujui pemilik saat ini, seperti yang disimpan oleh pemilik sebelumnya, menunggu di bawah barisnya dalam daftar lingkungan dan di editor. Pemilik server melihat “Berjalan di server ini. Setujui agar bisa dimulai.” dengan Setujui, yang menyimpannya tanpa perubahan; semua orang lain melihat “Berjalan di server ini. Pemilik server harus menyetujuinya sebelum bisa dimulai.”
  • Lingkungan yang ditahan untuk persetujuan itu menyatakan “Pemilik server belum menyetujui lingkungan ini, sehingga tidak dapat berjalan di server ini.” Pemilik server justru melihat “Anda belum menyetujui lingkungan ini. Lingkungan ini berjalan di server ini, jadi akan dimulai setelah Anda menyetujui definisinya.” dengan Tinjau dan setujui, yang membuka definisinya.
  • Terminal proses lingkungan, dan terminal yang dibuka saat mulai ketika ia membutuhkan Anda, berjalan di host server. Mengetik di salah satunya, mengubah ukurannya, atau menutupnya memerlukan akses tulis ke setiap repositori yang diekspos space, yang dapat dibaca melalui proses masuk forge Anda sendiri: sama seperti memulai lingkungan. Orang lain tidak dapat menjangkau terminal tersebut sama sekali.

Repo compose sederhana hanya membutuhkan ini:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

Semua hal lain memiliki nilai default: file compose ditemukan, setiap layanan berjalan, port ditetapkan, endpoint HTTP dideteksi, dan lingkungan diberi nama sesuai branch.

Lingkungan adalah daftar komponen berurutan. Masing-masing menunggu komponen sebelumnya siap, kecuali after menyebut yang lain, dan penghentian berjalan terbalik. enabledWhen membuat komponen bergantung pada opsi atau peran, misalnya opt.seed, !opt.seed, atau repo.web. Komponen yang perannya opsional dan tidak ada di space dikecualikan dengan cara yang sama, tanpa perlu enabledWhen: komponen itu tidak dimulai dan tidak memiliki {port.*} atau {url.*}, sehingga komponen lain yang membacanya gagal saat memulai.

Jenis Siapa yang menjalankan Kegunaan
compose Driver compose Control Center File compose apa pun, satu per lingkungan
cli Alat Anda. Control Center memanggil kata kerja yang dipetakan dan membaca JSON Alat yang memiliki siklus hidup, domain, dan datanya sendiri
process Control Center, dalam sesi terminal yang diawasi Server dev dan worker
task Control Center, sekali per pemicu Instalasi, migrasi, pengujian
app Control Center, saat seseorang mengklik Luncurkan Aplikasi desktop

Komponen task menerima daftar when:

Pemicu Berjalan
provision Saat worktree dibuat (lihat tugas worktree di bawah)
create Sekali per lingkungan, dan lagi setelah reset
start Pada setiap mulai
change Setelah sinkronisasi, saat jalur yang berubah cocok dengan onChange
manual Atas permintaan: Jalankan, cc-env run <id>, atau environment_run_task
archive Tepat sebelum worktree dihancurkan

Tugas yang tidak punya pekerjaan saat proses mulai menampilkan status Menganggur dan tidak masuk daftar langkah yang ditampilkan saat lingkungan dimulai: tugas manual atau change, atau tugas create yang sudah pernah dijalankan.

Perintah yang diberikan sebagai array adalah argv, sehingga nilai opsi tidak pernah melewati shell. String, atau script dengan array baris, berjalan di bawah bash -lc. Placeholder seperti {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>}, dan {url.<role>} hanya diperluas di argv. Perintah shell membaca nilai yang sama sebagai variabel CC_ENV_*, misalnya $CC_ENV_PORT_WEB. Placeholder yang tidak dikenal di komponen yang ikut serta menghentikan proses mulai sebelum ada yang dijalankan.

Setiap perintah dan terminal space juga mendapatkan CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>, dan, di space PR, CC_PR_NUMBER serta CC_PR_IS_FORK. Dengan komponen compose, mereka juga mendapatkan COMPOSE_PROJECT_NAME dan COMPOSE_FILE, sehingga docker compose exec dalam tugas mencapai proyek yang benar.

Definisi mengikat peran ke repo ruang kerja, sehingga satu stack dapat mencakup beberapa repo:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: space dapat memulai lingkungan jika memiliki setidaknya satu peran jangkar. Jika dua definisi cocok, orang yang memulai memilih.
  • required: stack tidak dapat berjalan tanpa repo ini.
  • whenMissing: yang terjadi saat space tidak memiliki peran tersebut. addToSpace menambahkan repo pada branch default-nya dan merupakan default untuk peran required. useSource meneruskan checkout terdaftar Anda, yang harus diperlakukan hanya baca. skip membiarkan variabel tidak disetel dan merupakan default lainnya.
  • Memulai memerlukan izin write pada repo jangkar di space dan akses baca ke setiap repo terikat lainnya.

Perintah berjalan di peran pertama yang dideklarasikan dalam repos, tidak pernah di peran lain yang kebetulan dimiliki space, sehingga definisi satu repo tidak pernah menyebutkannya. Komponen apa pun dapat menggantinya dengan "cwd": { "role": "e2e", "path": "packages/ui" }. Kedua bidang bersifat opsional. Ketika peran pertama mungkin tidak ada di sebuah space, karena peran itu bukan required dan bukan satu-satunya anchor, setiap komponen harus menyebut perannya.

Control Center menetapkan port host sebelum apa pun dimulai, dari rentang yang berlaku untuk seluruh host (42000 sampai 49999 secara default, dalam blok berisi 32). Port tetap sama selama lingkungan hidup, dan port compose hanya terikat ke 127.0.0.1.

  • Port compose tidak perlu dideklarasikan. Baca sebagai {port.postgres.5432} atau CC_ENV_PORT_POSTGRES_5432.
  • Port lain dideklarasikan di tempat penggunaannya, dengan "port": "web" atau "ports": ["web", "hmr"], dan dibaca sebagai {port.web}. Proses dengan port juga mendapatkan PORT dan HOST=127.0.0.1.

Endpoint HTTP mendapatkan URL di router server, yang mendengarkan pada satu port loopback:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> adalah branch sebagai slug, atau pr-<n> di space PR. <project> adalah naming.project, atau nama definisi jika tidak ada.
  • Nama *.localhost mengarah ke loopback, sehingga tidak memerlukan entri hosts atau DNS, dan nama host memisahkan cookie antar lingkungan.
  • Port compose yang menjawab HTTP terdeteksi, dan http pada komponen menggantikan tebakan itu. Proses memerlukan "endpoint": { "role": "web", "primary": true }, yang juga menyediakan {url.web}.
  • Di browser (VM), gunakan Buka di Browser (VM). https://web--fix-login--shop.localhost/ mencapai rute yang sama di sana.
  • Seluruh label tetap dalam 63 karakter, sehingga nama panjang dipendekkan dengan hash.
  • Dua endpoint tidak berbagi domain induk. Aplikasi yang membutuhkan satu cookie di keduanya harus menyajikannya dari satu endpoint.

Untuk URL yang harus didaftarkan terlebih dahulu, seperti pengalihan OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } memberikan sekumpulan nama tetap.

policy menentukan kapan lingkungan berjalan. autoCreate bernilai off, prSpaces, atau allSpaces, idleStopMinutes default-nya 240, followPrHead menyinkronkan lingkungan PR saat head-nya bergerak, dan dengan maxRunning (default 6) Mulai menawarkan untuk menghentikan lingkungan yang paling lama tidak digunakan.

Aplikasi web dan Postgres dari satu file compose, dengan .env yang diabaikan git, migrasi, dan tugas pengujian. seedFiles menyalin file bernama dari checkout terdaftar Anda ke setiap worktree baru.

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks memungkinkan layanan tanpa pemeriksaan kesehatan sendiri menahan komponen berikutnya. Tanpanya, kontainer yang berjalan dianggap siap, dan migrasi bisa mendahului basis data yang masih memulai.

Setiap mulai dan refresh menjalankan up dengan --remove-orphans, sehingga layanan yang dihapus dari file compose berhenti dan membebaskan port-nya. Image dibangun saat mulai dan saat refresh, kecuali komponen menetapkan "build": false.

Alat rekaan acme yang memiliki kontainer, domain, dan TLS-nya sendiri. Control Center memberikan {name} dan mengetahui sisanya dari status. Control Center tidak pernah menurunkan nama host alat dan tidak pernah mengedit /etc/hosts.

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • create, status, dan destroy wajib ada. Control Center memilih create atau start dari status yang dibacanya. Kata kerja apa pun boleh berupa { "shell": "…" } alih-alih argv.
  • interactive menyebutkan kata kerja, dari create, start, dan reset, yang dapat meminta apa yang dibutuhkan di terminal. Ketika kata kerja seperti itu keluar dengan kode 3 untuk orang yang menekan Mulai, Control Center menjalankan ulang kata kerja yang sama di tab terminal, dan proses mulai berlanjut setelah kata kerja itu keluar dengan kode 0. Di sana kondisi interactive bernilai benar dan CC_ENV_INTERACTIVE=1 diatur, sehingga { "if": "!interactive", "args": ["--json"] } mempertahankan output mesin untuk pipe. Mulai oleh agen, atau mulai otomatis, tidak pernah membuka terminal: lingkungan menampilkan Perlu tindakan dan menunggu.
  • destroy yang gagal tetap menghapus lingkungan jika status kemudian melaporkan missing, sehingga lingkungan yang sudah tidak dimiliki alat selalu bisa dihapus.
  • list memungkinkan Control Center menyadari lingkungan yang telah hilang dari alat. Lingkungan hanya ditandai hilang ketika namanya tidak ada di list dan status kemudian menyatakan missing. Output yang tidak dapat dibaca sebagai daftar tidak mengubah apa pun.
  • {service} di logs dan exec harus berupa satu kata yang tidak diawali -, dan salah satu layanan yang dilaporkan alat terakhir kali, jika alat pernah melaporkan layanan.
  • statusMap membaca JSON alat dengan penunjuk JSON, dengan * cocok dengan setiap item. Aturan status berurutan dan kecocokan pertama menang. Kondisi berupa path dengan equals, atau any maupun none dengan where.
  • keepsDataOnStop: false mematikan penghentian saat diam dan menambahkan peringatan kehilangan data ke Berhenti. Setel ini jika penghentian menghilangkan data.
  • routing.mode: "tool" menghubungkan nama host alat ke browser (VM) dan agen. Domain harus berakhir dengan .test, .localhost, atau .internal, dan URL yang dilaporkan di luarnya dibuang.

Alat milik Anda dapat melewati statusMap dan mencetak kontrak status yang dijelaskan di akhir halaman ini.

Hanya proses dan tugas, tanpa kontainer. Aplikasi web menemukan API melalui {url.api}.

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • Setiap proses adalah tab terminal yang dapat Anda buka, baca, dan ketik, jika Anda memiliki akses tulis ke setiap repositori dalam space (lihat Siapa yang dapat menyimpan apa). Menutup tab tidak menghentikannya.
  • ready menerima http (URL lengkap), tcp (host:port), atau logMatch (ekspresi reguler). restart bernilai on-failure (default), always, atau never. restartOn memulai ulang proses saat jalur yang berubah cocok.
  • options menjadi formulir pada Mulai, dan agentDefault berlaku untuk eksekusi yang dimulai agen.

Aplikasi desktop dengan langkah build. Aplikasi bekerja sama saja apa pun teknologinya, karena Control Center bekerja di tingkat jendela OS dan tidak memerlukan hook atau SDK di aplikasi.

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

Aplikasi tidak dimulai bersama lingkungan. Seseorang mengklik Luncurkan, dan prepare berjalan lebih dulu. Bangun ulang & luncurkan ulang menjalankan pasangan itu lagi. enabledWhen berlaku untuk aplikasi dan untuk tugas prepare-nya, dan Luncurkan ditolak selama salah satunya nonaktif. Aplikasi dianggap berjalan selama ada proses dalam grup prosesnya yang berjalan, jadi peluncur yang memulai aplikasi lalu keluar tidak masalah. Jika semuanya hilang dalam sekitar 5 detik setelah Luncurkan, aplikasi tampil gagal dengan baris log terakhirnya. Setelah itu, keluar bersih tampil sebagai tertutup dan crash menampilkan baris log terakhir, dan keduanya tidak memulai ulangnya. Restart server menutup aplikasi dan tidak pernah meluncurkannya kembali, dan penghentian saat diam membiarkan aplikasi yang berjalan.

  • Di macOS, berikan Control Center izin Perekaman Layar dan Aksesibilitas satu kali di Pengaturan Sistem. Host server memerlukan sesi GUI: server headless menolak meluncurkan aplikasi.
  • Luncurkan biner secara langsung. open -a menyerahkan aplikasi ke LaunchServices dan aplikasi keluar dari pohon proses yang dilacak Control Center, sehingga aplikasi tampil gagal tepat setelah diluncurkan.
  • Jendela tetap berada di layar. macOS tidak menangkap jendela yang diparkir di luar semua layar, sehingga aplikasi yang digunakan agen terlihat di layar server. Fokus tidak diperlukan.
  • "isolate": "home" memberi aplikasi direktori home pribadi melalui HOME, XDG_*, dan CFFIXED_USER_HOME, sehingga salinan dari dua space dapat berjalan berdampingan. NSUserDefaults tidak terisolasi, sehingga preferensi Cocoa dan shared_preferences Flutter tetap dibagi antar salinan.
  • isolate hanya berlaku untuk proses yang diluncurkan. Peluncur toolchain seperti flutter run membutuhkan home yang sebenarnya, jadi pasangkan isolate dengan biner hasil build. Jika aplikasi memiliki pengaturan sendiri, seperti --user-data-dir, utamakan itu.
  • Agen mengendalikan jendela dengan app_use, yang hanya dapat mencapai pohon proses lingkungan ini. Agen melihat jendela, bukan desktop. Peluncuran oleh agen melewati kebijakan tindakan dan default-nya bertanya, dan input agen berhenti saat seseorang memegang kendali.
  • "input": "background" (default) mengirim peristiwa ke proses. "foreground" mengaktifkan jendela dan mengambil alih kursor.

Tugas provision dan archive menjalankan penyiapan dan pembongkaran repo bersama worktree-nya. Ikon di baris repo pada Pengaturan → Ruang kerja → Repositori membuka definisi repo tersebut.

Tugas ini mengikuti worktree, bukan lingkungan, sehingga berjalan di space tempat tidak ada yang mengklik Mulai:

provision archive
Berjalan Saat worktree peran dibuat, di space mana pun Tepat sebelum worktree itu dihancurkan
Saat gagal Provisioning gagal dan worktree dihancurkan Dicatat, tidak pernah memblokir penghapusan
Batas waktu default 5 menit 2 menit
Melihat CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME Sama

Repo tanpa stack hanya membutuhkan definisi yang berisi tugasnya. Karena tidak ada yang perlu dimulai, peran jangkar tidak diperlukan:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • Belum ada lingkungan, sehingga tugas ini tidak dapat memakai {name}, {port.*}, {url.*}, {opt.*}, atau enabledWhen, dan tidak mendapatkan env definisi.
  • Hanya satu definisi yang boleh memiliki tugas provision dan archive untuk sebuah repo. Definisi lain tetap boleh mengikatnya untuk hal lainnya.
  • "when": ["provision", "change"] juga memasang ulang saat lockfile berubah.
  • Tugas berjalan untuk worktree dari peran cwd-nya, sehingga definisi multi-repo dapat menyiapkan setiap repo secara terpisah.
  • Eksekusi uji menyetel CC_SCRIPT_TEST=1. Percobaan ulang dimulai dari worktree bersih, jadi tulis tugas yang tahan dijalankan ulang.

Agen tidak pernah mendapatkan soket Docker. Di space dengan definisi yang memenuhi syarat, eksekusi mendapatkan cc-env di PATH-nya. Space berasal dari eksekusi, sehingga agen hanya dapat bertindak pada lingkungannya sendiri, dan setiap perintah melewati kebijakan tindakan.

Jendela terminal
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

Dengan komponen compose, shim docker juga mengizinkan docker compose dengan ps, logs, exec, port, restart, dan top, dan hanya terhadap proyek compose milik lingkungan ini. Tidak boleh ada flag sebelum kata kerja, dan setiap kata kerja menerima sejumlah kecil opsi: logs tidak dapat mengikuti output, dan exec hanya menerima -T (atau --no-tty). Opsi yang mengarahkan compose ke berkas atau proyek lain (-f, -p, --project-directory, --env-file, --profile) ditolak di mana pun muncul. Yang lain keluar dengan kode 5 dan “not available in Control Center agent runs”.

Repo yang skill-nya memanggil alatnya sendiri dapat terus melakukannya. Blok agentPassthrough pada komponen cli mendeklarasikan perintah yang boleh dijalankan agen. Hanya perintah yang dideklarasikan oleh definisi yang disetujui yang diteruskan, dan setiap perintah berjalan di host, sehingga berlaku aturan Jalankan perintah di host, yang secara bawaan meminta izin terlebih dahulu:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps menyebut operasi yang kebijakannya berlaku. positionalName memaksa argumen itu ke lingkungan space ini, nameFilter memfilter output JSON untuknya, dan setiap nilai pathFlags harus mengarah ke dalam worktree eksekusi. Perintah yang tidak cocok dengan aturan apa pun keluar dengan kode 5.

Operasi yang sama tersedia sebagai alat: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app, dan environment_stop_app. Agen dalam sandbox mencapai port mereka secara langsung dan nama host lingkungan mereka melalui proxy eksekusi, jadi minta mereka membaca endpoint dari environment_status alih-alih menebak URL.

Kode PR dari fork tidak tepercaya, dan pada penempatan host kode itu berjalan sebagai pengguna OS server. policy.forkPrs menentukan yang terjadi:

Nilai Efek Default untuk
rig File compose berjalan di VM tanpa pertanyaan Definisi yang hanya memiliki komponen compose dan task
approval Setiap mulai memerlukan admin Semua definisi lain
deny Ditolak Tidak ada
  • seedFiles tidak pernah disalin untuk fork, karena biasanya berisi rahasia. File compose yang mengikat salah satunya melaporkan file yang hilang berdasarkan nama.
  • Tugas provision dan archive dilewati kecuali kebijakannya rig, dan dalam hal itu tugas berjalan di VM.
  • Pada penempatan host, privileged, namespace host, bind soket Docker, devices, dan bind di luar worktree space ditolak pada fork. Di space tepercaya, hal itu hanya memberi peringatan.

"placement": "rig" menjalankan komponen compose dan task di microVM khusus. Definisi dengan komponen process, cli, atau app tidak memenuhi syarat. File compose berjalan tanpa perubahan, tanpa soket Docker host dan tanpa kredensial operator, dan akses jaringan dibatasi pada registri yang dibutuhkan image-nya. Worktree dipasang secara langsung.

  • Guest arm64. Guest adalah arm64 di Apple Silicon, sehingga image yang hanya amd64 tidak akan berjalan.
  • Registri privat ditolak. Guest tidak memiliki kredensial registri, sehingga image di registri di luar yang publik dikenal ditolak sebelum VM menyala. Repositori privat di registri publik gagal saat guest menariknya.
  • Penyimpanan 16 GiB. Semua image dan volume stack berbagi satu disk 16 GiB, dan tidak dapat diperbesar.
  • Boot pertama lambat. Lapisan image bersifat per VM, sehingga boot pertama menarik semuanya. Rig yang dihentikan mempertahankan disknya.
  • Image dasar harus dapat dibaca. Dockerfile yang menyebut image dasarnya melalui variabel tidak dapat direncanakan, karena akses jaringan ditetapkan saat boot.
  • Masa hidup. policy.rigTtlHours mengakhiri VM, secara default setelah 24 jam.

Komponen cli tanpa statusMap mengharapkan kontrak bawaan, cc-env/1. Kata kerja status mencetak objek ini ke stdout:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state bernilai ready, starting, stopped, failed, atau missing. missing mengarah ke create, sedangkan stopped dan failed mengarah ke start. Laporkan missing dengan kode keluar 0: status yang gagal dihitung sebagai failed.
  • Hanya state yang diperlukan. Bidang yang tidak dikenal diabaikan, dan output yang tidak dapat diurai tampil sebagai menurun, dengan teks mentah sebagai detail.
  • URL harus berupa loopback, *.localhost, atau berada di bawah routing.domain, jika tidak URL dibuang.
  • needsRecreate: true menampilkan Buat ulang, yang membuang data. Control Center tidak pernah bertindak sendiri berdasarkan ini.
  • Kata kerja list mencetak array JSON berisi nama, atau objek dengan name.

Kode keluar berlaku untuk setiap kata kerja:

Kode Arti
0 OK
3 Jawaban diperlukan di terminal, misalnya kata sandi sudo. Kata kerja yang tercantum di interactive dijalankan ulang di tab terminal untuk orang yang menekan Mulai. Jika tidak, Jalankan di terminal membuka terminal space dengan command alat sudah diketik tetapi belum dijalankan, lalu Coba lagi mencoba lagi. Control Center tidak pernah menjalankan sudo dan tidak pernah menjawab prompt
4 Perlu masuk. command alat menjelaskan caranya
5 Sesuatu yang bergantung padanya tidak tersedia, misalnya runtime kontainer yang tidak berjalan
Lainnya Kegagalan

Kode 3, 4, dan 5 bukan kegagalan. Lingkungan menampilkan Perlu tindakan dan menunggu, dan mulai berikutnya melanjutkan dari titik tempat mulai tadi berhenti. Tugas yang keluar dengan salah satu kode tersebut memiliki arti yang sama.

Kemajuan dikirim ke stderr sebagai JSON yang dipisahkan baris:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

Saat lingkungan dimulai, panel menampilkan komponen yang dilalui proses mulai, masing-masing dengan spinner, tanda centang, atau tanda silang. Baris step menyatakan apa yang sedang dilakukan alat sekarang, dan label-nya tampil di bawah baris alat itu sendiri; langkah tidak pernah menambah baris. state sebuah langkah adalah pending, running, done, atau failed, dan langkah tanpa state dianggap sedang berjalan. Langkah yang melaporkan lagi dengan id yang sama (berupa string atau angka, atau dengan label yang sama jika tanpa id) menggantikan apa yang dikatakannya sebelumnya, sehingga alat dengan satu spinner dapat mempertahankan satu id dan mengubah label. Tanpa id, langkah berurutan: langkah baru mengakhiri langkah sebelumnya. Saat perintah keluar, langkah yang masih berjalan berakhir sesuai cara perintah itu berakhir.

Baris log memuat satu baris keluaran alat yang dibungkus JSON, dan dibaca sebagai keluaran teks biasa. Baris note masuk ke output proses, dan yang memiliki "level": "warn" juga tetap ada di lingkungan sebagai peringatan. Baris terakhir bertipe error menjadi galat terstruktur, dengan command ditawarkan untuk disalin, dan 12 baris keluaran terakhir tampil di bawah message-nya. Tanpanya, Control Center menampilkan 20 baris stderr terakhir. Apa pun yang bukan JSON adalah output log biasa.