{"id":29675775,"url":"https://github.com/oxidecomputer/falcon","last_synced_at":"2025-07-22T23:38:40.241Z","repository":{"id":103489769,"uuid":"399673447","full_name":"oxidecomputer/falcon","owner":"oxidecomputer","description":"Fast Assessment Laboratory for Computers On Networks","archived":false,"fork":false,"pushed_at":"2025-07-07T15:10:16.000Z","size":5084,"stargazers_count":7,"open_issues_count":24,"forks_count":3,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-07-07T16:27:18.439Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxidecomputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-08-25T03:07:17.000Z","updated_at":"2025-07-07T15:10:18.000Z","dependencies_parsed_at":"2023-05-20T17:15:32.683Z","dependency_job_id":"92b0e820-25c1-42c6-a3f4-30737514e6a0","html_url":"https://github.com/oxidecomputer/falcon","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/falcon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Ffalcon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Ffalcon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Ffalcon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Ffalcon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/falcon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Ffalcon/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266591232,"owners_count":23953082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T23:38:33.234Z","updated_at":"2025-07-22T23:38:40.227Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FALCON\n\n**_Fast Assessment Laboratory for Computers On Networks_**\n\nFalcon is a Rust API for creating network topologies composed of\n[Propolis](https://github.com/oxidecomputer/propolis) VMs interconnected by\nsimnet links. It's designed to be used for both automated testing and as a\ndevelopment environment for networked systems.\n\n## Requirements\n\n- Falcon runs on Helios \u003e= 1.0.20707\n- Falcon uses [propolis](https://github.com/oxidecomputer/propolis) which\n  requires hardware virtualization support. Running Falcon on bare metal is\n  recommended. While nested virt can be made to work, it often requires wizardry\n  and is known to have flaky behaviors.\n\n## QuickStart\n\nTo get a ready-to-go Falcon project use the\n[falcon-template](https://github.com/oxidecomputer/falcon-template).\n\n\n```shell\ncargo generate --git https://github.com/oxidecomputer/falcon-template --name duo\n```\n\nThis will create a cargo project with the following topology.\n\n```Rust\nuse libfalcon::{cli::run, error::Error, Runner, unit::gb};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Error\u003e {\n\n    let mut d = Runner::new(\"duo\");\n\n    // nodes\n    let violin = d.node(\"violin\", \"helios-2.5\", 4, gb(4));\n    let piano = d.node(\"piano\", \"helios-2.5\", 4, gb(4));\n\n    // links\n    d.link(violin, piano);\n\n    run(\u0026mut d).await?;\n\n    Ok(())\n}\n```\n\n### Launch the topology\n\nThe following will launch the VMs in your topology and do some basic setup. When\nthe call returns, your topology is ready to use.\n\n```shell\ncargo build\npfexec ./target/debug/duo launch\n```\n\n### Get a serial connection to a node\n\nOnce the topology is up, you can access the nodes via serial connection. Tap the\nenter key a few times after running the serial command below. To exit the\nconsole use `ctl-q`.\n\n```shell\n./target/debug/duo serial violin\n```\n\n### Destroy the topology\n\n```shell\npfexec ./target/debug/duo destroy\n```\n\n### Learn More\n\n- The primary reference documentation is in the [wiki](https://github.com/oxidecomputer/falcon/wiki/Reference).\n- [Working examples](examples).\n\n## Building and testing\n\nThis assumes that that the instructions in the install section have been run.\n\n```\ncargo build\ncargo test -- --test-threads 1\ncargo test -- --test-threads 1 --ignored\n```\n\nNote that `cargo test` will automatically use `pfexec` to run tests; this is configured in\n[.cargo/config.toml](.cargo/config.toml).\n\nBy default, topology and configuration for a falcon deployment is placed into\na hardcoded  `$PWD/.falcon` directory. However, users can override this by\nsetting the `Runner::falcon_dir` variable inside their code, and/or by passing\na `--falcon-dir \u003cDIR\u003e` parameter to most CLI commands. This allows tests and\ncode to be run independently as long as the names of the runners and nodes are\nunique.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Ffalcon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Ffalcon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Ffalcon/lists"}